stratal 0.0.26 → 0.1.0

package/dist/route-registration.service-COKBZTsn.mjs

@@ -0,0 +1,1265 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import { C as ROUTER_TOKENS, _ as defineMetadata, g as getMethodInjections, l as Singleton, p as inject, r as DI_TOKENS, v as getMetadata } from "./di-DQ3xbjgf.mjs";
+import { n as __decorateParam, t as __decorate } from "./decorate-C79yt3Wt.mjs";
+import { LOGGER_TOKENS } from "./logger/index.mjs";
+import { d as HttpException, f as abort } from "./errors-CrOXI_y5.mjs";
+import { a as RouterContext, c as METHOD_STATUS_CODES, d as SECURITY_SCHEMES, l as ROUTER_CONTEXT_KEYS, o as DEFAULT_CONTENT_TYPE, s as HTTP_METHODS, u as ROUTE_METADATA_KEYS } from "./exception-context-CdnGTQNF.mjs";
+import { o as RouterError, s as createThrottleMiddleware } from "./module-registry-lkQPDuQe.mjs";
+import { t as isGatewayMode } from "./gateway-mode-0rUaeW3g.mjs";
+import { i as getControllerRoute, r as getControllerOptions } from "./controller.decorator-BB0JcwMg.mjs";
+import { i as getMethodGuards, r as getControllerGuards, t as GuardExecutionService } from "./guards-DOGly9IF.mjs";
+import { r as ResponseCacheConfigError, t as CachePurgeError } from "./response-cache.error-B4D0zy9W.mjs";
+import { c as getCacheable, i as cachingUnavailableReason, l as RESPONSE_CACHE_TOKENS, o as getPurgesCache, t as bindRouteCache, u as createLoopbackPurgeTarget } from "./route-cache-binding-CrLh8tB6.mjs";
+import { n as getRateLimits } from "./rate-limit.decorator-PYQ9EYqs.mjs";
+import { a as getWsOnCloseMethod, o as getWsOnErrorMethod, s as getWsOnMessageMethod, t as GatewayContext, u as isGateway } from "./gateway-context-Cmc1NRS0.mjs";
+import { i as extractPathParams, r as generateConventionRouteName, s as toOpenAPIPath } from "./route-name-BslSbmMP.mjs";
+import { object } from "zod/mini";
+import { validator } from "hono/validator";
+//#region src/router/errors/schema-validation.error.ts
+var SchemaValidationError = class extends HttpException {
+	issues;
+	constructor(zodError) {
+		super(400, "Schema validation failed");
+		this.issues = zodError.issues.map((err) => ({
+			path: err.path.join("."),
+			message: err.message,
+			code: err.code
+		}));
+	}
+	reportContext() {
+		return { issues: this.issues };
+	}
+};
+//#endregion
+//#region src/router/errors/index.ts
+/**
+* Error thrown when a signed URL has an invalid or expired signature.
+*
+* HTTP Status: 403 Forbidden
+*/
+var InvalidSignatureError = class extends HttpException {
+	constructor() {
+		super(403, "Invalid or expired signature");
+	}
+};
+/**
+* ResponseValidationError
+*
+* Thrown when a controller's response body does not match the declared Zod response schema.
+* Indicates a server-side schema mismatch — the controller is returning data that
+* violates its own API contract.
+*/
+var ResponseValidationError = class extends HttpException {
+	issues;
+	constructor(zodError) {
+		super(500, "Response validation failed");
+		this.issues = zodError.issues.map((err) => ({
+			path: err.path.join("."),
+			message: err.message,
+			code: err.code
+		}));
+	}
+};
+//#endregion
+//#region src/router/middleware/domain.middleware.ts
+/**
+* Parse a domain pattern into a regex and extract parameter names.
+*
+* @example
+* parseDomainPattern('{tenant}.example.com')
+* // => { regex: /^([^.]+)\.example\.com$/, paramNames: ['tenant'] }
+*
+* parseDomainPattern('{region}.{tenant}.example.com')
+* // => { regex: /^([^.]+)\.([^.]+)\.example\.com$/, paramNames: ['region', 'tenant'] }
+*/
+function parseDomainPattern(pattern) {
+	const paramNames = [];
+	const escaped = pattern.replace(/\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g, (_match, paramName) => {
+		paramNames.push(paramName);
+		return "([^.]+)";
+	}).replace(/\./g, "\\.");
+	return {
+		regex: new RegExp(`^${escaped}$`),
+		paramNames
+	};
+}
+/**
+* Strip port number from a host header value.
+* 'example.com:8787' => 'example.com'
+*/
+function stripPort(host) {
+	const colonIdx = host.lastIndexOf(":");
+	if (colonIdx === -1) return host;
+	const afterColon = host.slice(colonIdx + 1);
+	return /^\d+$/.test(afterColon) ? host.slice(0, colonIdx) : host;
+}
+/**
+* Create a Hono middleware that matches the request host against a domain pattern.
+*
+* When the host matches, domain parameters are extracted and stored in context
+* variables accessible via `ctx.domain(key)`.
+*
+* When the host does NOT match, aborts with 404.
+*
+* @param pattern - Domain pattern with `{param}` placeholders (e.g., '{tenant}.myapp.com')
+*
+* @example
+* ```typescript
+* // Applied automatically by RouteRegistrationService for controllers with domain config
+* @Controller('/dashboard', { domain: '{tenant}.myapp.com' })
+* export class DashboardController {
+*   async index(ctx: RouterContext) {
+*     const tenant = ctx.domain('tenant')
+*   }
+* }
+* ```
+*/
+function createDomainMiddleware(pattern) {
+	const { regex, paramNames } = parseDomainPattern(pattern);
+	return async (c, next) => {
+		const host = stripPort(c.req.header("host") ?? "");
+		const match = regex.exec(host);
+		if (!match) abort(404, "Domain mismatch");
+		for (let i = 0; i < paramNames.length; i++) c.set(`domain:${paramNames[i]}`, match[i + 1]);
+		await next();
+	};
+}
+//#endregion
+//#region src/router/middleware/middleware-chain.ts
+/**
+* Create a Hono middleware handler that executes a chain of Stratal middleware classes.
+*
+* Each middleware is resolved from the request-scoped container per request,
+* then executed in order (first registered = outermost in the chain).
+*
+* @param classes - Middleware classes to chain
+* @returns Hono middleware handler
+*/
+function createMiddlewareChain(classes) {
+	return async (c, next) => {
+		const requestContainer = c.get(ROUTER_CONTEXT_KEYS.REQUEST_CONTAINER);
+		const ctx = new RouterContext(c);
+		let current = next;
+		for (let i = classes.length - 1; i >= 0; i--) {
+			const prevNext = current;
+			const middlewareClass = classes[i];
+			current = async () => {
+				const middleware = requestContainer.resolve(middlewareClass);
+				let called = false;
+				const guardedNext = () => {
+					if (called) return Promise.reject(new RouterError(`Middleware "${middlewareClass.name ?? "anonymous"}" called next() multiple times`));
+					called = true;
+					return prevNext();
+				};
+				const result = await middleware.handle(ctx, guardedNext);
+				if (result instanceof Response) c.res = result;
+				return result;
+			};
+		}
+		const result = await current();
+		if (result instanceof Response) return result;
+	};
+}
+//#endregion
+//#region src/router/decorators/route.decorator.ts
+/**
+* Decorator to add OpenAPI metadata to a controller method using convention-based routing.
+*
+* **Cannot be mixed with HTTP method decorators** (`@Get`, `@Post`, `@Put`, `@Patch`,
+* `@Delete`, `@All`) in the same controller. Use one pattern or the other.
+*
+* Stores route configuration (schemas, response, tags, security) in metadata.
+* HTTP method, path, and success status code are auto-derived from the method name:
+* - index() → GET /base-path → 200
+* - show() → GET /base-path/:id → 200
+* - create() → POST /base-path → 201
+* - update() → PUT /base-path/:id → 200
+* - patch() → PATCH /base-path/:id → 200
+* - destroy() → DELETE /base-path/:id → 200
+*
+* @param config - Route configuration (schemas, response, tags, security)
+*
+* @example
+* ```typescript
+* @Controller('/api/v1/notes', {
+*   tags: ['Notes'],
+*   security: ['bearerAuth']
+* })
+* export class NotesController implements Controller {
+*   @Route({
+*     body: createNoteSchema,
+*     response: noteSchema, // 201 auto-derived from 'create' method
+*     tags: ['Mutations'],
+*     description: 'Create a new note'
+*   })
+*   async create(ctx: RouterContext): Promise<Response> {
+*     // POST /api/v1/notes (auto-derived from method name)
+*     // Body schema: createNoteSchema (auto-validated)
+*     // Response: 201 → noteSchema (status auto-derived)
+*     // Tags: ['Notes', 'Mutations'] (merged with controller)
+*     // Security: ['bearerAuth'] (inherited from controller)
+*     const body = ctx.body()
+*     const note = await this.notesService.create(body)
+*     return ctx.json(note, 201)
+*   }
+*
+*   @Route({
+*     query: paginationSchema,
+*     response: array(noteSchema) // 200 auto-derived from 'index' method
+*   })
+*   async index(ctx: RouterContext): Promise<Response> {
+*     // GET /api/v1/notes (auto-derived)
+*     // Query params auto-validated
+*     const notes = await this.notesService.list()
+*     return ctx.json(notes)
+*   }
+*
+*   @Route({
+*     params: object({ id: uuid() }),
+*     response: {
+*       schema: noteSchema,
+*       description: 'Note details'
+*     },
+*     security: [] // Override to make public
+*   })
+*   async show(ctx: RouterContext): Promise<Response> {
+*     // GET /api/v1/notes/:id (auto-derived)
+*     // URL params auto-validated
+*     // Response: 200 → noteSchema (status auto-derived)
+*     // Security: [] (public route, override controller security)
+*     const id = ctx.param('id')
+*     const note = await this.notesService.findById(id)
+*     return ctx.json(note)
+*   }
+* }
+* ```
+*/
+function Route(config) {
+	return function(target, propertyKey, descriptor) {
+		const metadata = {
+			type: "convention",
+			config
+		};
+		defineMetadata(ROUTE_METADATA_KEYS.ROUTE_CONFIG, metadata, target, propertyKey);
+		const existing = getMetadata(ROUTE_METADATA_KEYS.DECORATED_METHODS, target) ?? [];
+		existing.push(propertyKey);
+		defineMetadata(ROUTE_METADATA_KEYS.DECORATED_METHODS, existing, target);
+		return descriptor;
+	};
+}
+/**
+* Get the route metadata from a controller method
+*
+* @param target - Controller instance or prototype
+* @param methodName - Name of the method
+* @returns Route metadata or undefined if not decorated
+*/
+function getRouteMetadata(target, methodName) {
+	return getMetadata(ROUTE_METADATA_KEYS.ROUTE_CONFIG, target, methodName);
+}
+/**
+* Get all methods with route decorators (@Route, @Get, @Post, etc.) from a controller
+*
+* @param ControllerClass - Controller class
+* @returns Array of method names that have route metadata
+*/
+function getRouteDecoratedMethods(ControllerClass) {
+	const methods = /* @__PURE__ */ new Set();
+	let proto = ControllerClass.prototype;
+	while (proto && proto !== Object.prototype) {
+		const own = getMetadata(ROUTE_METADATA_KEYS.DECORATED_METHODS, proto);
+		if (own) for (const m of own) methods.add(m);
+		proto = Object.getPrototypeOf(proto);
+	}
+	return [...methods];
+}
+//#endregion
+//#region src/router/services/capture-payload.ts
+/** Does any declared tag template read the `{data.*}` scope? */
+function readsDataScope(tags) {
+	return (tags ?? []).some((tag) => tag.includes("{data."));
+}
+/**
+* Whether this route needs its handler's JSON payload captured.
+*
+* Evaluated once at route registration, never per request: capturing
+* unconditionally would clone and re-parse every JSON response body in the
+* application, doubling parse cost on a hot path that has nothing to do with
+* caching.
+*/
+function needsPayloadCapture(cacheable, purges) {
+	return readsDataScope(cacheable?.tags) || readsDataScope(purges?.tags);
+}
+/**
+* Matches the JSON family: `application/json` plus any `+json` structured
+* suffix (`application/problem+json`, `application/ld+json`,
+* `application/vnd.api+json`), with or without parameters.
+*/
+const JSON_CONTENT_TYPE = /^application\/(?:[\w.-]+\+)?json\s*(?:;|$)/i;
+/**
+* Record the handler's structured payload so `{data.*}` cache tags can read
+* values the request itself never carried — a post's category ID on a publish
+* route.
+*
+* **This does not decide what is cacheable.** Every content type Workers
+* Caching stores — HTML, text, images, binary, streams — is cached exactly the
+* same way; `@Cacheable` is content-type agnostic. This function only decides
+* whether a tag can interpolate a value *out of the response body*, which
+* requires a body that parses into an object. Non-JSON routes still cache
+* normally and can still tag from `{param.*}` and `{query.*}` — never
+* `{body.*}`, which `bindRouteCache` rejects at registration because the
+* router never has a parsed request body available to populate it.
+* Inertia sets the payload directly when building its page response, so its
+* HTML documents support
+* `{data.*}` without any parsing here.
+*
+* Clones before reading: consuming the returned Response's body would leave
+* nothing to send.
+*/
+async function capturePayload(c, response) {
+	if (c.get(ROUTER_CONTEXT_KEYS.RESPONSE_PAYLOAD)) return;
+	if (!JSON_CONTENT_TYPE.test(response.headers.get("Content-Type") ?? "")) return;
+	try {
+		c.set(ROUTER_CONTEXT_KEYS.RESPONSE_PAYLOAD, await response.clone().json());
+	} catch {}
+}
+//#endregion
+//#region src/router/validation/create-validator.ts
+/**
+* Build a Hono validator middleware that runs a Zod schema against one request
+* part and populates `c.req.valid(target)` with the parsed (coerced) output.
+*
+* This is the plain-Hono replacement for `@hono/zod-openapi`'s `app.openapi()`
+* validator composition. It carries **no runtime `zod` import** — it only calls
+* `safeParseAsync` on the caller-supplied schema instance and references
+* `ZodType`/`ZodError` as erased types — so a route without a declared schema
+* attaches no validator and pulls in no `zod`.
+*
+* Parsing is async so a schema may carry an async refinement — one that reaches
+* a database, a cache or a service binding to decide whether a value is
+* acceptable. Zod's synchronous `safeParse` throws `$ZodAsyncError` rather than
+* returning a failure when it meets one, which would surface as a 500 instead
+* of a 400. A fully synchronous schema resolves on the same tick.
+*
+* On failure it throws {@link SchemaValidationError}, which the global exception
+* handler renders as a 400 with i18n-translated issues (the Zod error map is
+* installed globally by the I18n module, so messages stay localized).
+*
+* `omit` drops framework-injected request keys (e.g. the `locale` path segment
+* on localized routes) before parsing, so they never reach a user's schema —
+* keeping a `.strict()` schema from rejecting them and keeping `c.req.valid()`
+* limited to the keys the schema actually declares.
+*/
+function createValidator(target, schema, omit) {
+	return validator(target, async (value) => {
+		const record = value;
+		const input = omit?.length ? omitKeys(record, omit) : record;
+		const result = await schema.safeParseAsync(input);
+		if (!result.success) throw new SchemaValidationError(result.error);
+		return result.data;
+	});
+}
+function omitKeys(value, keys) {
+	const out = {};
+	for (const key in value) if (!keys.includes(key)) out[key] = value[key];
+	return out;
+}
+//#endregion
+//#region src/router/validation/route-validators.ts
+/** The framework-injected path key on localized routes; never part of a user schema. */
+const LOCALE_PARAM_KEY = "locale";
+/** Map a body content type to the Hono validation target. */
+function bodyTarget(contentType) {
+	return contentType.includes("json") ? "json" : "form";
+}
+/**
+* Assemble the ordered validator middlewares for a route from its declared
+* schemas. Order matches Hono's expectation (param → query → body) and only
+* includes validators for parts the route actually declares.
+*/
+function buildRouteValidators(schemas) {
+	const validators = [];
+	if (schemas.params) validators.push(createValidator("param", schemas.params, schemas.isLocaleVariant ? [LOCALE_PARAM_KEY] : void 0));
+	if (schemas.query) validators.push(createValidator("query", schemas.query));
+	if (schemas.body) validators.push(createValidator(bodyTarget(schemas.body.contentType), schemas.body.schema));
+	return validators;
+}
+//#endregion
+//#region src/router/services/route-registration.service.ts
+var route_registration_service_exports = /* @__PURE__ */ __exportAll({ RouteRegistrationService: () => RouteRegistrationService });
+const invokeHandler = async (instance, method, ...args) => {
+	return await instance[method](...args);
+};
+/** True for anything with a callable `.then` — a `Promise`, or a thenable. */
+function isThenable(value) {
+	return typeof value === "object" && value !== null && typeof value.then === "function";
+}
+let RouteRegistrationService = class RouteRegistrationService {
+	logger;
+	registry;
+	routerResolver;
+	localePathService;
+	app;
+	moduleRegistry;
+	metadataRegistry;
+	cacheability;
+	responseCache;
+	responseCacheOptions;
+	gatewayRouteTable;
+	partitionResolver;
+	controllerClasses = /* @__PURE__ */ new Map();
+	upgradeWebSocketFn = null;
+	cacheableRouteCount = 0;
+	/**
+	* Whether Workers Caching is usable, answered once per entrypoint.
+	*
+	* Keyed on whether the request arrived through the gateway, because that is
+	* the scope the answer actually has: a gateway topology runs two entrypoints
+	* — `cache.enabled` false on the gateway, true on the cached one — over a
+	* single isolate and therefore a single instance of this service. A verdict
+	* reached on one says nothing about the other, so holding one for the
+	* isolate lets whichever entrypoint happens to serve the first request
+	* decide for both, and a `cache.enabled` that is false *by design* on the
+	* gateway reads as the app being misconfigured.
+	*
+	* Memoized rather than recomputed because `cache.enabled` is a static
+	* Wrangler setting: within one entrypoint the answer cannot change.
+	*/
+	cachingAvailability = /* @__PURE__ */ new Map();
+	constructor(logger, registry, routerResolver, localePathService, app, moduleRegistry, metadataRegistry, cacheability, responseCache, responseCacheOptions, gatewayRouteTable, partitionResolver) {
+		this.logger = logger;
+		this.registry = registry;
+		this.routerResolver = routerResolver;
+		this.localePathService = localePathService;
+		this.app = app;
+		this.moduleRegistry = moduleRegistry;
+		this.metadataRegistry = metadataRegistry;
+		this.cacheability = cacheability;
+		this.responseCache = responseCache;
+		this.responseCacheOptions = responseCacheOptions;
+		this.gatewayRouteTable = gatewayRouteTable;
+		this.partitionResolver = partitionResolver;
+	}
+	/**
+	* The cached entrypoint named by `forRoot({ gateway: { entrypoint } })`, or
+	* `undefined` when no gateway is configured.
+	*
+	* A `Promise` (the `forRootAsync` trap) reads as "no gateway" here rather
+	* than throwing: `responseCacheDefaults()` raises that as its own boot error
+	* with a message about the real problem, and it is called first on every
+	* path that consults this.
+	*/
+	gatewayEntrypoint() {
+		const options = this.responseCacheOptions;
+		if (isThenable(options)) return void 0;
+		return options?.gateway?.entrypoint;
+	}
+	/** `gateway.keyBy`, read under the same `forRootAsync` caveat as the entrypoint. */
+	gatewayKeyBy() {
+		const options = this.responseCacheOptions;
+		if (isThenable(options)) return [];
+		return options?.gateway?.keyBy ?? [];
+	}
+	/**
+	* `ResponseCacheModule.forRoot({ defaults })`, resolved once at
+	* construction (constructor injection is memoized on this singleton
+	* instance) and falling back to `{}` when the module was never imported —
+	* mirrors `OpenAPIConfigStore.getBaseConfig()`.
+	*
+	* `forRootAsync({ useFactory })` is a trap here: `ModuleRegistry` registers
+	* the factory verbatim (`registerFactory`), and `Container.resolve()` never
+	* awaits a factory's return value — so an async `useFactory` resolves this
+	* token to a **Promise**, not the options object. Left unchecked, `?.defaults`
+	* on a Promise is `undefined`, silently falling back to `{}` — including
+	* silently dropping a `partitionBy` the author thought was enforced, the
+	* exact per-user data leak this feature exists to prevent. Detected and
+	* thrown here, once, at boot, rather than trusted per route.
+	*/
+	responseCacheDefaults() {
+		const options = this.responseCacheOptions;
+		if (isThenable(options)) throw new ResponseCacheConfigError("ResponseCacheModule.forRootAsync() options resolved to a Promise, not the awaited value. Route registration reads `defaults` synchronously — an async `useFactory` is never awaited before routes register, so `defaults` (and any `partitionBy` inside it) would be silently dropped instead of enforced, and every `@Cacheable` route would register as if no defaults were set. Use a synchronous `useFactory`, or resolve the options yourself and register them with `useValue` once the async work has settled.");
+		return options?.defaults ?? {};
+	}
+	/**
+	* Configure router with controllers and global middleware.
+	* Resolves controllers from ModuleRegistry and global middleware from RouterResolver.
+	*/
+	async configure() {
+		const controllers = this.moduleRegistry.getAllControllers();
+		const globalMiddleware = this.routerResolver?.getGlobalMiddleware() ?? [];
+		this.gatewayRouteTable?.configure(this.gatewayEntrypoint(), this.gatewayKeyBy());
+		this.logger.info("Registering controllers", { controllerCount: controllers.length });
+		if (globalMiddleware.length > 0) this.app.use("*", createMiddlewareChain(globalMiddleware));
+		if (controllers.some(isGateway)) {
+			const { upgradeWebSocket } = await import("hono/cloudflare-workers");
+			this.upgradeWebSocketFn = upgradeWebSocket;
+		}
+		const actions = /* @__PURE__ */ new WeakMap();
+		for (const ControllerClass of controllers) this.collectRoutes(ControllerClass, actions);
+		for (const route of this.registry.all()) actions.get(route)?.();
+		this.logger.info("Controller registration complete");
+	}
+	/**
+	* Pass 1: Collect routes from a controller into RouteRegistry and store Hono actions.
+	* Versioning and locale expansion are handled by RouteRegistry.register().
+	*/
+	collectRoutes(ControllerClass, actions) {
+		const isWsGateway = isGateway(ControllerClass);
+		const controllerRoute = getControllerRoute(ControllerClass);
+		if (!controllerRoute) throw new RouterError(`Controller "${ControllerClass.name}" registration failed: ${isWsGateway ? "Missing @Gateway decorator or route metadata" : "Missing @Controller decorator or route metadata"}`);
+		const controllerOpts = getControllerOptions(ControllerClass);
+		const controllerGuards = getControllerGuards(ControllerClass)?.guards ?? [];
+		const routerConfig = this.routerResolver?.resolveForController(ControllerClass) ?? { middleware: [] };
+		const classThrottleMiddleware = Array.from(new Set(getRateLimits(ControllerClass).map(createThrottleMiddleware)));
+		const basePath = routerConfig.prefix ? this.joinPaths(routerConfig.prefix, controllerRoute) : controllerRoute;
+		const effectiveVersion = controllerOpts?.version ?? routerConfig.version;
+		const effectiveDomain = controllerOpts?.domain ?? routerConfig.domain;
+		if (isWsGateway) {
+			const wsMiddleware = [...routerConfig.middleware, ...classThrottleMiddleware];
+			const expandedRoutes = this.registry.register({
+				method: "ws",
+				basePath,
+				version: effectiveVersion,
+				domain: effectiveDomain,
+				controller: ControllerClass.name,
+				action: "ws",
+				hidden: routerConfig.hideFromDocs ?? false,
+				middleware: wsMiddleware.map((m) => m.name)
+			});
+			for (const route of expandedRoutes) actions.set(route, () => {
+				if (wsMiddleware.length > 0) this.app.use(route.path, createMiddlewareChain(wsMiddleware));
+				if (effectiveDomain) {
+					const domainHandler = createDomainMiddleware(effectiveDomain);
+					this.app.use(route.path, domainHandler);
+					this.app.use(`${route.path}/*`, domainHandler);
+				}
+				this.registerGatewayForPath(ControllerClass, route.path, controllerGuards);
+			});
+			return;
+		}
+		const className = ControllerClass.name;
+		this.controllerClasses.set(className, ControllerClass);
+		const prototype = ControllerClass.prototype;
+		if (prototype.handle) {
+			if (getCacheable(prototype, "handle") || getPurgesCache(prototype, "handle")) throw new ResponseCacheConfigError(`${className}.handle: @Cacheable/@PurgesCache is not supported on wildcard controllers (those implementing \`handle()\`) yet — the decorator would be silently ignored, never firing and never warning, because wildcard routes do not go through per-method cache binding. Remove the decorator, or restructure this route as a decorated method.`);
+			const wildcardMiddleware = [...routerConfig.middleware, ...classThrottleMiddleware];
+			const expandedRoutes = this.registry.register({
+				method: "all",
+				basePath,
+				version: effectiveVersion,
+				domain: effectiveDomain,
+				controller: className,
+				action: "handle",
+				hidden: routerConfig.hideFromDocs ?? false,
+				middleware: wildcardMiddleware.map((m) => m.name)
+			});
+			for (const route of expandedRoutes) actions.set(route, () => {
+				if (wildcardMiddleware.length > 0) this.app.use(route.path, createMiddlewareChain(wildcardMiddleware));
+				this.registerWildcardRoute(ControllerClass, route.path);
+			});
+			return;
+		}
+		const decoratedMethods = getRouteDecoratedMethods(ControllerClass);
+		if (decoratedMethods.length === 0) throw new RouterError(`Controller "${ControllerClass.name}" registration failed: No route decorators found. Use @Route() or HTTP method decorators (@Get, @Post, etc.) on controller methods.`);
+		const methodMetadata = [];
+		let hasConvention = false;
+		let hasExplicit = false;
+		for (const m of decoratedMethods) {
+			const meta = getRouteMetadata(prototype, m);
+			if (!meta) continue;
+			methodMetadata.push({
+				method: m,
+				meta
+			});
+			if (meta.type === "convention") hasConvention = true;
+			else if (meta.type === "explicit") hasExplicit = true;
+		}
+		if (hasConvention && hasExplicit) throw new RouterError(`Controller "${ControllerClass.name}" registration failed: Cannot mix @Route() with HTTP method decorators (@Get, @Post, etc.) in the same controller. Use one pattern or the other.`);
+		const routerHidden = routerConfig.hideFromDocs;
+		const controllerHidden = controllerOpts?.hideFromDocs ?? false;
+		const routerName = routerConfig.name;
+		const controllerName = controllerOpts?.name;
+		const effectiveNamePrefix = routerName && controllerName ? `${routerName}${controllerName}` : routerName ?? controllerName;
+		for (const { method: methodName, meta } of methodMetadata) {
+			const resolved = this.resolveMethodAndPath(meta, methodName, basePath, className);
+			if (!resolved) continue;
+			const methodThrottleMiddleware = getRateLimits(prototype, methodName).map(createThrottleMiddleware);
+			const effectiveMiddleware = Array.from(/* @__PURE__ */ new Set([
+				...routerConfig.middleware,
+				...classThrottleMiddleware,
+				...methodThrottleMiddleware
+			]));
+			const middlewareNames = effectiveMiddleware.map((m) => m.name);
+			const { httpMethod, fullPath, routeConfig: rawRouteConfig, statusCodeOverride } = resolved;
+			let mergedParams = rawRouteConfig.params;
+			if (routerConfig.params) {
+				const prefixShape = routerConfig.params.shape;
+				mergedParams = mergedParams ? object({
+					...mergedParams.shape,
+					...prefixShape
+				}) : routerConfig.params;
+			}
+			const routeConfig = mergedParams === rawRouteConfig.params ? rawRouteConfig : {
+				...rawRouteConfig,
+				params: mergedParams
+			};
+			const hideFromDocs = routeConfig.hideFromDocs ?? routerHidden ?? controllerHidden;
+			let routeName;
+			if (routeConfig.name) routeName = effectiveNamePrefix ? `${effectiveNamePrefix}${routeConfig.name}` : routeConfig.name;
+			else if (meta.type === "convention") {
+				const autoName = generateConventionRouteName(basePath, methodName);
+				routeName = effectiveNamePrefix ? `${effectiveNamePrefix}${autoName}` : autoName;
+			}
+			const expandedRoutes = this.registry.register({
+				name: routeName,
+				method: httpMethod,
+				basePath: fullPath,
+				version: effectiveVersion,
+				domain: effectiveDomain,
+				controller: className,
+				action: methodName,
+				hidden: hideFromDocs,
+				middleware: middlewareNames
+			});
+			const methodGuards = getMethodGuards(prototype, methodName)?.guards ?? [];
+			const allGuards = methodGuards.length > 0 ? [...controllerGuards, ...methodGuards] : controllerGuards;
+			const responseSchema = httpMethod !== "all" ? this.extractResponseSchema(routeConfig) : null;
+			const cacheableOptions = getCacheable(prototype, methodName);
+			const purgesCacheOptions = getPurgesCache(prototype, methodName);
+			const capturesPayload = needsPayloadCapture(cacheableOptions, purgesCacheOptions);
+			const cacheBinding = bindRouteCache(cacheableOptions, purgesCacheOptions, this.responseCacheDefaults(), {
+				controller: className,
+				method: methodName,
+				guarded: allGuards.length > 0,
+				routeParams: extractPathParams(fullPath),
+				gatewayConfigured: this.gatewayEntrypoint() !== void 0
+			});
+			if (cacheBinding && (!this.cacheability || !this.responseCache)) throw new ResponseCacheConfigError(`${className}.${methodName}: @Cacheable/@PurgesCache requires ResponseCacheModule to be imported. Without it, the decorator would be silently dropped — the route would register and run normally, just never cache or purge anything, with no warning at boot or at request time. Add \`ResponseCacheModule.forRoot({ defaults: { ttl } })\` to your app's \`imports\`.`);
+			if (cacheBinding?.cacheable || cacheBinding?.purges) this.cacheableRouteCount++;
+			const partitionBy = cacheBinding?.cacheable?.partitionBy ?? [];
+			if (partitionBy.length > 0) this.partitionResolver?.assertKnown(partitionBy, `${className}.${methodName}`);
+			const handler = this.createControllerHandler(ControllerClass, methodName, responseSchema, capturesPayload, cacheBinding);
+			for (const route of expandedRoutes) {
+				if (partitionBy.length > 0) {
+					const methods = httpMethod === "all" ? ["GET", "HEAD"] : [httpMethod];
+					for (const method of methods) this.gatewayRouteTable?.record(method, route.path, partitionBy);
+				}
+				actions.set(route, () => {
+					if (effectiveDomain) {
+						const domainHandler = createDomainMiddleware(effectiveDomain);
+						this.app.use(route.path, domainHandler);
+						this.app.use(`${route.path}/*`, domainHandler);
+					}
+					if (allGuards.length > 0) this.logger.info(`Route guards`, {
+						controller: className,
+						method: httpMethod.toUpperCase(),
+						path: route.path,
+						methodName,
+						guardCount: allGuards.length
+					});
+					if (httpMethod === "all") {
+						this.logger.info(`Registering @All route`, {
+							controller: className,
+							path: route.path,
+							methodName
+						});
+						if (effectiveMiddleware.length > 0) this.app.use(route.path, createMiddlewareChain(effectiveMiddleware));
+						if (allGuards.length > 0) this.app.use(route.path, this.createGuardMiddleware(allGuards));
+						this.app.all(route.path, handler);
+						return;
+					}
+					const isLocaleVariant = route.isLocaleVariant ?? false;
+					const body = this.resolveBody(routeConfig);
+					const validators = buildRouteValidators({
+						params: routeConfig.params,
+						query: routeConfig.query,
+						body,
+						isLocaleVariant
+					});
+					const wrappedHandler = this.wrapHandlerWithChain(handler, effectiveMiddleware, allGuards);
+					this.logger.info(`Registering route`, {
+						controller: className,
+						method: httpMethod.toUpperCase(),
+						path: route.path,
+						methodName,
+						hidden: route.hidden
+					});
+					this.app.on(httpMethod.toUpperCase(), [route.path], ...validators, wrappedHandler);
+					const metadata = this.mergeMetadata(controllerOpts, routeConfig, ControllerClass, methodName);
+					this.metadataRegistry.add(this.buildRouteMetadata({
+						method: httpMethod,
+						path: route.path,
+						routeConfig,
+						metadata,
+						body,
+						methodName: meta.type === "convention" ? methodName : void 0,
+						statusCodeOverride,
+						isLocaleVariant,
+						hidden: route.hidden
+					}));
+				});
+			}
+		}
+	}
+	/**
+	* Register a single WebSocket gateway route
+	*/
+	registerGatewayForPath(GatewayClass, fullPath, guards) {
+		const onMsgMethod = getWsOnMessageMethod(GatewayClass);
+		const onCloseMethod = getWsOnCloseMethod(GatewayClass);
+		const onErrMethod = getWsOnErrorMethod(GatewayClass);
+		const wsHandler = this.upgradeWebSocketFn((c) => {
+			const gateway = new RouterContext(c).getContainer().resolve(GatewayClass);
+			const events = {};
+			const bindWsHandler = (method, onCatch) => {
+				return (evt, ws) => {
+					const ctx = new GatewayContext(c, ws);
+					invokeHandler(gateway, method, evt, ctx).catch((err) => {
+						this.logger.error(`WebSocket ${method} handler error`, err, { gateway: GatewayClass.name });
+						onCatch?.(err, ws);
+					});
+				};
+			};
+			if (onMsgMethod) events.onMessage = bindWsHandler(onMsgMethod, (_err, ws) => ws.close(1011, "Internal Error"));
+			if (onCloseMethod) events.onClose = bindWsHandler(onCloseMethod);
+			else events.onClose = (_evt, ws) => {
+				ws.close();
+			};
+			if (onErrMethod) events.onError = bindWsHandler(onErrMethod);
+			return events;
+		});
+		this.nameHandler(wsHandler, GatewayClass.name, onMsgMethod ?? "[anonymous]", "ws");
+		this.logger.info("Registering WebSocket gateway", {
+			gateway: GatewayClass.name,
+			path: fullPath
+		});
+		const handlers = [];
+		if (guards.length > 0) {
+			this.logger.info("Gateway guards", {
+				gateway: GatewayClass.name,
+				path: fullPath,
+				guardCount: guards.length
+			});
+			handlers.push(this.createGuardMiddleware(guards));
+		}
+		handlers.push(wsHandler);
+		this.app.get(fullPath, ...handlers);
+	}
+	/**
+	* Create a guard execution middleware
+	*
+	* This middleware executes all guards for a route before the handler.
+	* Guards are executed in order; all must pass for the request to proceed.
+	*
+	* @param guards - Array of guards to execute
+	* @returns Hono middleware function
+	*/
+	createGuardMiddleware(guards) {
+		const guardService = new GuardExecutionService(this.logger);
+		return async (c, next) => {
+			const ctx = new RouterContext(c);
+			const container = ctx.getContainer();
+			await guardService.executeGuards(guards, ctx, container);
+			await next();
+		};
+	}
+	/**
+	* Wrap a controller handler with a `scopedMiddleware → guards → handler`
+	* chain that runs *inside* the Hono route handler — after request
+	* validators have populated `c.req.valid(...)`. This is the only place
+	* we can run user middleware after `@hono/zod-openapi`'s validators in
+	* the same pipeline.
+	*
+	* Returns a Hono handler with the same signature as the original so
+	* `app.openapi(route, wrapped)` works transparently.
+	*/
+	wrapHandlerWithChain(handler, scopedMiddleware, guards) {
+		if (scopedMiddleware.length === 0 && guards.length === 0) return handler;
+		const scopedChain = scopedMiddleware.length > 0 ? createMiddlewareChain(scopedMiddleware) : null;
+		const guardChain = guards.length > 0 ? this.createGuardMiddleware(guards) : null;
+		return async (c) => {
+			let captured;
+			const runHandler = async () => {
+				captured = await handler(c);
+			};
+			const runGuards = guardChain ? () => guardChain(c, runHandler) : runHandler;
+			const result = await (scopedChain ? () => scopedChain(c, runGuards) : runGuards)();
+			if (result instanceof Response) return result;
+			return captured;
+		};
+	}
+	/**
+	* Register wildcard route for non-RESTful controllers
+	*/
+	registerWildcardRoute(ControllerClass, route) {
+		this.logger.info(`Registering wildcard route`, {
+			controller: ControllerClass.name,
+			route: `${route}/:path{.+}`,
+			method: "ALL"
+		});
+		const handler = this.createControllerHandler(ControllerClass, "handle");
+		this.app.all(route, handler);
+		this.app.all(`${route}/:path{.+}`, handler);
+	}
+	/**
+	* Resolve HTTP method, path, route config, and status code from route metadata.
+	*/
+	resolveMethodAndPath(meta, methodName, basePath, className) {
+		if (meta.type === "convention") {
+			const derived = this.deriveHttpMethodAndPath(methodName, basePath);
+			if (!derived) throw new RouterError(`Cannot derive HTTP method/path for convention-based route "${className}.${methodName}". Ensure the method name follows the naming convention (e.g., index, create, show).`);
+			return {
+				httpMethod: derived.method,
+				fullPath: derived.path,
+				routeConfig: meta.config,
+				statusCodeOverride: meta.config.statusCode
+			};
+		}
+		return {
+			httpMethod: meta.method,
+			fullPath: this.joinPaths(basePath, meta.path),
+			routeConfig: meta.config,
+			statusCodeOverride: meta.config.statusCode
+		};
+	}
+	/**
+	* Join a base path and a route path, normalizing slashes
+	*/
+	joinPaths(basePath, routePath) {
+		if (basePath.endsWith("/")) basePath = basePath.slice(0, -1);
+		if (routePath === "/" || routePath === "") return basePath || "/";
+		if (!routePath.startsWith("/")) routePath = "/" + routePath;
+		return basePath + routePath;
+	}
+	/**
+	* Auto-derive HTTP method and path from controller method name
+	* Uses HTTP_METHODS constant for RESTful convention mapping
+	*/
+	deriveHttpMethodAndPath(methodName, basePath) {
+		if (!(methodName in HTTP_METHODS)) return null;
+		const mapping = HTTP_METHODS[methodName];
+		return {
+			method: mapping.method,
+			path: basePath + mapping.path
+		};
+	}
+	/**
+	* Merge controller-level and route-level metadata
+	* Tags are merged (appended), security is merged (union)
+	* Guards automatically add sessionCookie security if present
+	*/
+	mergeMetadata(controllerOpts, routeConfig, ControllerClass, methodName) {
+		const tags = [...controllerOpts?.tags ?? [], ...routeConfig.tags ?? []];
+		const groups = [...controllerOpts?.groups ?? [], ...routeConfig.groups ?? []];
+		const prototype = ControllerClass.prototype;
+		const hasMethodGuards = (getMethodGuards(prototype, methodName)?.guards.length ?? 0) > 0;
+		const hasControllerGuards = (getControllerGuards(ControllerClass)?.guards.length ?? 0) > 0;
+		const requiresAuth = hasMethodGuards || hasControllerGuards;
+		let security = [];
+		if (routeConfig.security !== void 0) security = [...controllerOpts?.security ?? [], ...routeConfig.security];
+		else if (controllerOpts?.security) security = controllerOpts.security;
+		if (requiresAuth && !security.includes(SECURITY_SCHEMES.SESSION_COOKIE)) security.push(SECURITY_SCHEMES.SESSION_COOKIE);
+		return {
+			tags,
+			security: security.length > 0 ? security.map((scheme) => ({ [scheme]: [] })) : [],
+			groups
+		};
+	}
+	/**
+	* Resolve a route's request body into its schema + content type, normalizing
+	* the bare-schema and `{ schema, contentType }` forms. Returns `undefined`
+	* when no body is declared. Shared by validator construction and metadata.
+	*/
+	resolveBody(routeConfig) {
+		if (!routeConfig.body) return void 0;
+		return {
+			schema: this.isRouteBodyObject(routeConfig.body) ? routeConfig.body.schema : routeConfig.body,
+			contentType: this.isRouteBodyObject(routeConfig.body) ? routeConfig.body.contentType ?? "application/json" : DEFAULT_CONTENT_TYPE
+		};
+	}
+	/**
+	* Build the schema metadata entry for a route. Consumed lazily by the OpenAPI
+	* generator — common error responses are added there, not here, so
+	* `common.schemas` (and the schemas it references) never reach the routing
+	* path. The `locale` path param of a localized route is recorded as plain
+	* metadata (enforced by the route pattern, read via `getLocale()`), so no zod
+	* enum is constructed at registration.
+	*/
+	buildRouteMetadata(input) {
+		const { routeConfig, metadata } = input;
+		const successStatus = input.statusCodeOverride ?? (input.methodName ? METHOD_STATUS_CODES[input.methodName] : void 0) ?? 200;
+		const responses = [];
+		const responseDef = routeConfig.response;
+		if (responseDef && this.isRouteResponseObject(responseDef)) responses.push({
+			status: successStatus,
+			schema: responseDef.schema,
+			contentType: responseDef.contentType ?? "application/json",
+			description: responseDef.description ?? `Response ${successStatus}`
+		});
+		else responses.push({
+			status: successStatus,
+			schema: responseDef,
+			contentType: DEFAULT_CONTENT_TYPE,
+			description: `Response ${successStatus}`
+		});
+		const localeConfig = this.localePathService.localePathConfig;
+		const localeParam = input.isLocaleVariant && localeConfig ? {
+			name: "locale",
+			values: localeConfig.prefixedLocales
+		} : void 0;
+		const entry = {
+			method: input.method,
+			path: toOpenAPIPath(input.path),
+			hidden: input.hidden ?? false,
+			tags: metadata.tags,
+			security: metadata.security,
+			request: {
+				params: routeConfig.params,
+				query: routeConfig.query,
+				body: input.body
+			},
+			responses,
+			localeParam
+		};
+		if (routeConfig.summary) entry.summary = routeConfig.summary;
+		if (routeConfig.description) entry.description = routeConfig.description;
+		if (metadata.groups.length > 0) entry.groups = metadata.groups;
+		return entry;
+	}
+	/**
+	* Check if a body definition is a RouteBodyObject (has schema key) vs bare ZodType
+	*/
+	isRouteBodyObject(body) {
+		return typeof body === "object" && "schema" in body;
+	}
+	/**
+	* Resolve method parameter injections from the container
+	*
+	* @param prototype - Controller prototype
+	* @param methodName - Method name to get injections for
+	* @param container - Request-scoped container
+	* @returns Array of resolved dependencies in parameter order
+	*/
+	resolveMethodInjections(prototype, methodName, container) {
+		const injections = getMethodInjections(prototype, methodName);
+		if (!injections.length) return [];
+		return injections.map((inj) => container.resolve(inj.token));
+	}
+	/**
+	* Name a handler function so Hono's inspectRoutes() can identify it.
+	* Format: `{type}:{Controller}.{method}` (e.g. `http:UsersController.create`)
+	*/
+	nameHandler(fn, controller, method, type = "http") {
+		Object.defineProperty(fn, "name", { value: `${type}:${controller}.${method}` });
+	}
+	/**
+	* Create controller handler that resolves controller from request-scoped container
+	* This ensures each request gets a fresh controller with request-scoped context
+	*/
+	createControllerHandler(ControllerClass, methodName, responseSchema = null, capturesPayload = false, cacheBinding) {
+		const handler = async (c) => {
+			const override = c.get("validationSuccessResponse");
+			if (override) return override;
+			const ctx = new RouterContext(c);
+			const requestContainer = ctx.getContainer();
+			const controller = requestContainer.resolve(ControllerClass);
+			const method = controller[methodName];
+			if (typeof method === "function") {
+				const injectedArgs = this.resolveMethodInjections(ControllerClass.prototype, methodName, requestContainer);
+				const response = await method.apply(controller, [ctx, ...injectedArgs]);
+				if (capturesPayload) await capturePayload(c, response);
+				const validated = responseSchema && c.env.ENVIRONMENT !== "production" ? await this.validateResponse(response, responseSchema) : response;
+				return this.applyCacheDecision(c, validated, cacheBinding, {
+					controller: ControllerClass.name,
+					method: methodName
+				});
+			}
+			throw new RouterError(`Method "${methodName}" not found on controller "${ControllerClass.name}"`);
+		};
+		this.nameHandler(handler, ControllerClass.name, methodName);
+		return handler;
+	}
+	/**
+	* Apply this route's `@Cacheable`/`@PurgesCache` decision, if it has one.
+	*
+	* Deliberately does **not** stamp `no-store` for the "nothing to do" case
+	* (`!cacheBinding`, or `cacheBinding.cacheable` absent) — the outermost
+	* `createNoStoreFallbackMiddleware` (registered in `HonoApp`) catches every
+	* response that reaches Hono without a `Cache-Control`, this one included,
+	* so every response still gets an explicit decision without every call
+	* site needing to know that. This function only needs to handle the
+	* positive cases: computing `@Cacheable` headers, and firing `@PurgesCache`.
+	*
+	* `@PurgesCache` fires independently of `@Cacheable` — the common case is
+	* a mutation route (create/update/destroy) that isn't itself cacheable but
+	* must invalidate a GET route's cached entries on success. Gating the
+	* purge on `cacheBinding.cacheable` would silently skip that purge.
+	*
+	* **Headers stamped here are not the last word.** This runs *inside* the
+	* Hono route handler, so any outbound middleware — anything doing work
+	* after its own `await next()` — sees the response afterwards and can
+	* overwrite `Vary`, `Cache-Control`, or `Set-Cookie` with a plain
+	* `c.header(name, value)`, which replaces rather than appends. That is
+	* silent: the route still looks cached, but (for `Vary`) every variant
+	* collapses onto one entry. Middleware that contributes to any of these
+	* three headers must **merge** with what is already on the response, never
+	* set it outright — see `InertiaMiddleware`'s `Vary: X-Inertia` handling
+	* for the shape that fix takes.
+	*/
+	async applyCacheDecision(c, response, cacheBinding, routeContext) {
+		if (!cacheBinding) return response;
+		let scopes;
+		let result = response;
+		if (cacheBinding.cacheable && this.cachingAvailable(c)) {
+			if (!this.cacheability) throw new ResponseCacheConfigError("internal error: a route resolved a `@Cacheable` binding but CacheabilityService is unavailable. This should have been caught at registration — please file a bug.");
+			scopes = this.buildTagScopes(c);
+			result = this.cacheability.apply(result, cacheBinding.cacheable, scopes, {
+				partitionsResolved: this.partitionsResolved(c, cacheBinding.cacheable.partitionBy),
+				inertia: c.get("inertiaCacheSignals")
+			});
+		}
+		if (cacheBinding.purges && result.status >= 200 && result.status < 400) {
+			if (!this.responseCache) throw new ResponseCacheConfigError("internal error: a route resolved a `@PurgesCache` binding but ResponseCacheService is unavailable. This should have been caught at registration — please file a bug.");
+			scopes ??= this.buildTagScopes(c);
+			const cache = this.executionCache(c);
+			if (!cache) return result;
+			let spec;
+			try {
+				spec = this.responseCache.buildPurgeSpec(cacheBinding.purges, scopes);
+			} catch (error) {
+				const detail = error instanceof Error ? error.message : String(error);
+				this.logger.error("[stratal:response-cache] Failed to render @PurgesCache tags", {
+					controller: routeContext.controller,
+					action: routeContext.method,
+					path: c.req.routePath,
+					error: detail
+				});
+				throw new CachePurgeError(detail, error);
+			}
+			await this.responseCache.purge(spec, cache);
+		}
+		return result;
+	}
+	/**
+	* Whether this request's declared partitions are actually in the cache key.
+	*
+	* Reaching a controller **inline while running as the gateway** is, for a
+	* route with a non-empty `partitionBy`, proof that they are not: the
+	* dispatch middleware forwards every such `GET`/`HEAD` whose partitions it
+	* could resolve, so the only way one arrives here is that it declined —
+	* an unresolved resolver, a resolver that threw, or a primer that
+	* short-circuited. Reporting `true` there would stamp
+	* `Cache-Control: public, max-age=…` on a response the author declared
+	* per-caller, and while the gateway's own Workers cache is disabled, that
+	* header still travels to the client and to every intermediary between
+	* them. One user's dashboard in a shared proxy cache is exactly the leak
+	* `partitionBy` exists to prevent, so it fails closed instead.
+	*
+	* Inside the cached entrypoint the partitions normally *are* in the key,
+	* because the gateway chose `ctx.props` before forwarding. But that is the
+	* caller's claim, not a fact, and this entrypoint is reachable by anything
+	* that can name it — another Worker's service binding, a misrouted export,
+	* or our own gateway having selected an overlapping route's binding. So it
+	* is checked rather than trusted: every partition this route declared must
+	* be present in `ctx.props`. A caller that supplies none, or only some, gets
+	* `private, no-store` instead of a shared entry.
+	*
+	* With **no execution context at all** — `hono.fetch(request, env)`, which
+	* `quarry api` and `mcp serve` both do — there is no way to tell those cases
+	* apart, so unknown means uncacheable.
+	*
+	* An app with no gateway configured can never have a non-empty
+	* `partitionBy` (`bindRouteCache` rejects it at boot), so this returns
+	* `true` on the first line for every app that doesn't use the feature.
+	*/
+	partitionsResolved(c, partitionBy) {
+		if (partitionBy.length === 0) return true;
+		let ctx;
+		try {
+			ctx = c.executionCtx;
+		} catch {
+			return false;
+		}
+		if (isGatewayMode(ctx)) return false;
+		const props = ctx.props;
+		return partitionBy.every((name) => props?.[name] !== void 0);
+	}
+	/**
+	* `c.executionCtx` is a Hono getter that throws when the context wasn't
+	* constructed with one (e.g. a bare `app.fetch(request)` in a unit test) —
+	* unlike a plain optional property, there's no way to read it without a
+	* `try`/`catch` when it might be absent. `cache` itself is optional even
+	* when `executionCtx` exists: Wrangler only attaches it when `cache.enabled
+	* = true` is configured.
+	*
+	* The cast is necessary despite `@cloudflare/workers-types` declaring
+	* `cache?: CacheContext` on the *runtime* `ExecutionContext` — Hono's
+	* `Context.executionCtx` getter is typed against Hono's own narrower
+	* `ExecutionContext` interface (`waitUntil`/`passThroughOnException`/`props`
+	* only), not Cloudflare's, so TypeScript doesn't know `.cache` exists on
+	* what it returns even though the object handed to it at runtime does.
+	*
+	* **In gateway mode with a gateway configured, this is deliberately not
+	* `ctx.cache`.** Only partitioned `GET`/`HEAD` requests are forwarded to the
+	* cached entrypoint; every mutation — and so every `@PurgesCache` — runs
+	* inline in the gateway, whose Wrangler config sets `cache: { enabled:
+	* false }`. Purges are scoped to the entrypoint that issues them, so an
+	* inline purge would either find no `ctx.cache` at all (and 500 a mutation
+	* that already committed) or, if caching were left on for the gateway, purge
+	* the gateway's own cache — reporting success while invalidating nothing and
+	* leaving every cached read stale until its TTL ran out. Routing it over RPC
+	* to the cached entrypoint puts the purge where the entries actually live.
+	*/
+	/**
+	* Whether the entrypoint serving this request can cache.
+	*
+	* Reported once per entrypoint, at error level, because an app that declares
+	* `@Cacheable` and gets no caching is misconfigured somewhere — in a
+	* deployment that omitted `cache.enabled`, or in a local runtime that has no
+	* Workers Caching to offer. Either way its routes then serve uncached and
+	* say so in the response, rather than advertising a freshness nothing keeps.
+	*/
+	cachingAvailable(c) {
+		const gateway = this.isGatewayRequest(c);
+		const known = this.cachingAvailability.get(gateway);
+		if (known !== void 0) return known;
+		const reason = cachingUnavailableReason(this.cacheableRouteCount, this.executionCache(c));
+		this.cachingAvailability.set(gateway, reason === void 0);
+		if (reason !== void 0) this.logger.error(`[stratal:response-cache] ${reason}`);
+		return reason === void 0;
+	}
+	/**
+	* Whether this request came in through the gateway rather than the cached
+	* entrypoint. Both run the same Hono app over the same isolate, and only the
+	* execution context tells them apart.
+	*/
+	isGatewayRequest(c) {
+		try {
+			return isGatewayMode(c.executionCtx);
+		} catch {
+			return false;
+		}
+	}
+	executionCache(c) {
+		let ctx;
+		try {
+			ctx = c.executionCtx;
+		} catch {
+			return;
+		}
+		const entrypoint = this.gatewayEntrypoint();
+		if (entrypoint !== void 0 && isGatewayMode(ctx)) return createLoopbackPurgeTarget(ctx, entrypoint);
+		return ctx.cache;
+	}
+	/**
+	* Values available to `{scope.path}` cache tag templates for this request.
+	*
+	* `body` is deliberately `undefined`: the parsed request body isn't cheaply
+	* available at this point in the pipeline, and re-parsing it here would add
+	* a second parse to every request on the hot path just to support a rarely
+	* used tag scope. A `{body.*}` tag can therefore never resolve — but that's
+	* never discovered here, or at request time at all: `bindRouteCache`
+	* rejects any `@Cacheable`/`@PurgesCache` tag using the `body` scope at
+	* route registration, so a route that reaches this method never has one to
+	* render. (It was never true that both services "fail closed" on this —
+	* `CacheabilityService` does, but `@PurgesCache`'s `renderTags` call has no
+	* surrounding try/catch, so letting a `{body.*}` tag through would 500 the
+	* request after its mutation already committed, which is exactly why the
+	* boot-time check exists.)
+	*/
+	buildTagScopes(c) {
+		return {
+			param: c.req.param(),
+			query: c.req.query(),
+			body: void 0,
+			data: c.get(ROUTER_CONTEXT_KEYS.RESPONSE_PAYLOAD),
+			partition: this.partitionValues(c)
+		};
+	}
+	/**
+	* The partition values Cloudflare is keying this response on.
+	*
+	* Read from `ctx.props`, which is where the gateway put them and what the
+	* cache key is actually built from — so a `{partition.x}` tag names the same
+	* value the entry is stored under, on every variant of it.
+	*
+	* Empty when there is no execution context, or when running as the gateway
+	* (whose own responses are never stored). A tag naming a partition that is
+	* absent then fails to render, which fails the response closed — the right
+	* outcome, since the partition it claimed to be keyed by is not in the key.
+	*/
+	partitionValues(c) {
+		let ctx;
+		try {
+			ctx = c.executionCtx;
+		} catch {
+			return {};
+		}
+		if (isGatewayMode(ctx)) return {};
+		const values = {};
+		for (const [name, value] of Object.entries(ctx.props ?? {})) if (typeof value === "string") values[name] = value;
+		return values;
+	}
+	/**
+	* Extract the Zod schema from a RouteResponse definition.
+	* Returns null for non-JSON content types or when no response is defined.
+	*/
+	extractResponseSchema(routeConfig) {
+		const responseDef = routeConfig.response;
+		if (!responseDef) return null;
+		if (this.isRouteResponseObject(responseDef)) {
+			if (!(responseDef.contentType ?? "application/json").includes("application/json")) return null;
+			return responseDef.schema;
+		}
+		return responseDef;
+	}
+	/**
+	* Check if a response definition is a RouteResponseObject (has schema key) vs bare ZodType
+	*/
+	isRouteResponseObject(response) {
+		return typeof response === "object" && "schema" in response;
+	}
+	/**
+	* Validate a Response body against its declared Zod schema.
+	*
+	* Skips validation for:
+	* - Non-JSON content types
+	* - Empty bodies (204 No Content, 304 Not Modified)
+	*
+	* Clones the response to read the body without consuming the original stream.
+	*/
+	async validateResponse(response, schema) {
+		const contentType = response.headers.get("content-type");
+		if (!contentType || !contentType.includes("application/json")) return response;
+		if (response.status === 204 || response.status === 304) return response;
+		const cloned = response.clone();
+		let body;
+		try {
+			body = await cloned.json();
+		} catch {
+			return response;
+		}
+		const result = await schema.safeParseAsync(body);
+		if (!result.success) throw new ResponseValidationError(result.error);
+		return response;
+	}
+};
+RouteRegistrationService = __decorate([
+	Singleton(),
+	__decorateParam(0, inject(LOGGER_TOKENS.LoggerService)),
+	__decorateParam(1, inject(ROUTER_TOKENS.RouteRegistry)),
+	__decorateParam(2, inject(ROUTER_TOKENS.RouterResolver, { isOptional: true })),
+	__decorateParam(3, inject(ROUTER_TOKENS.LocalePathService)),
+	__decorateParam(4, inject(ROUTER_TOKENS.HonoApp)),
+	__decorateParam(5, inject(DI_TOKENS.ModuleRegistry)),
+	__decorateParam(6, inject(ROUTER_TOKENS.RouteMetadataRegistry)),
+	__decorateParam(7, inject(RESPONSE_CACHE_TOKENS.CacheabilityService, { isOptional: true })),
+	__decorateParam(8, inject(RESPONSE_CACHE_TOKENS.ResponseCacheService, { isOptional: true })),
+	__decorateParam(9, inject(RESPONSE_CACHE_TOKENS.Options, { isOptional: true })),
+	__decorateParam(10, inject(RESPONSE_CACHE_TOKENS.GatewayRouteTable, { isOptional: true })),
+	__decorateParam(11, inject(RESPONSE_CACHE_TOKENS.PartitionResolverService, { isOptional: true }))
+], RouteRegistrationService);
+//#endregion
+export { getRouteMetadata as a, parseDomainPattern as c, SchemaValidationError as d, getRouteDecoratedMethods as i, InvalidSignatureError as l, route_registration_service_exports as n, createMiddlewareChain as o, Route as r, createDomainMiddleware as s, RouteRegistrationService as t, ResponseValidationError as u };
+
+//# sourceMappingURL=route-registration.service-COKBZTsn.mjs.map