stratal 0.0.27 → 0.1.0

package/dist/{index-uybm0bhQ.d.mts → index-B2WtEagR.d.mts}

@@ -1,19 +1,31 @@
 import { t as Macroable } from "./index-0ItCjaqw.mjs";
 import { t as StratalEnv } from "./env-ug22bJj7.mjs";
-import { a as z, i as ZodError, o as zod_d_exports, t as OpenAPIHono } from "./zod-wecrEVAs.mjs";
+import { o as ZodObject, s as ZodType } from "./zod-BGisqLs3.mjs";
 import { c as LogLevel, r as LoggerService } from "./index-BUt92sAE.mjs";
 import { t as Constructor } from "./types-CmV_9xBD.mjs";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { SSEMessage, SSEStreamingApi, SSEStreamingApi as SSEStreamingApi$1 } from "hono/streaming";
+import { iso } from "zod/mini";
+import { Context, Hono, MiddlewareHandler } from "hono";
+import { DetectorOptions } from "hono/language";
 import { ContentfulStatusCode, RedirectStatusCode } from "hono/utils/http-status";
-import { Context, MiddlewareHandler, Next } from "hono";
 import { CookieOptions } from "hono/utils/cookie";
 import { StreamingApi, StreamingApi as StreamingApi$1 } from "hono/utils/stream";
-
+import { $ZodError } from "zod/v4/core";
 //#region src/errors/application-error.d.ts
 declare class ApplicationError extends Error {
   readonly timestamp: string;
   constructor(message?: string, cause?: unknown);
+  /**
+   * Extra structured fields this error contributes to its log entry.
+   *
+   * Override in a subclass to surface error-specific detail (codes, identifiers,
+   * validation issues) to observability. Returns `undefined` by default. Reserved
+   * log keys (`message`, `name`, `stack`, `timestamp`, `cause`) cannot be
+   * overridden — `cause` is populated from the error's cause chain — and
+   * globally-registered context still takes precedence over these fields.
+   */
+  reportContext(): Record<string, unknown> | undefined;
 }
 //#endregion
 //#region src/di/tokens.d.ts
@@ -114,7 +126,7 @@ type CurrentRoute = { [K in RouteName]: {
   name: K;
   params: NonNullable<RouteParams<K>>;
   defaults: Record<string, string>;
-} }[RouteName] | {
+}; }[RouteName] | {
   name: null;
   params: Record<string, string>;
   defaults: Record<string, string>;
@@ -138,14 +150,322 @@ type RouteMatcher = keyof StratalRouteMap extends never ? string : RouteName | `
  */
 type RoutePrefixes<S extends string> = S extends `${infer Head}.${infer Rest}` ? Head | `${Head}.${RoutePrefixes<Rest>}` : never;
 //#endregion
+//#region src/response-cache/tag-template.d.ts
+/**
+ * Values available to `{scope.path}` placeholders when rendering tags.
+ *
+ * `body` is never populated by the HTTP router — `RouteRegistrationService
+ * .buildTagScopes` always sets it `undefined`, and route registration now
+ * rejects any `{body.*}` tag at boot (`bindRouteCache`) precisely because
+ * nothing can ever fill it in on the request path. It stays part of this
+ * type — rather than being dropped — because `renderTags` is a general
+ * template compiler exercised directly in its own unit tests with hand-built
+ * scopes (including `body`); those tests are about the compiler accepting
+ * all four scopes correctly, independent of what any one caller can supply.
+ */
+interface TagScopes {
+  param: Record<string, string>;
+  query: Record<string, string>;
+  body: unknown;
+  data: unknown;
+  /**
+   * The partition values this request resolved, keyed by partition name.
+   *
+   * The only scope guaranteed present on every variant of a response. `data`
+   * is the resolved payload, and an Inertia partial reload carries only the
+   * props it asked for — so `{data.auth.user.id}` renders on the document and
+   * throws on the partial, which fails that variant closed and leaves exactly
+   * the deferred work uncached. A partition is in the cache key by
+   * construction, so `{partition.user}` renders identically on both.
+   */
+  partition: Record<string, string>;
+}
+//#endregion
+//#region src/router/middleware.interface.d.ts
+/**
+ * The continuation passed to a {@link Middleware}. Calling it runs the rest of
+ * the chain (the next middleware, then the route handler).
+ *
+ * It resolves to a short-circuit `Response` when a downstream middleware
+ * returns one, or `void` otherwise — wider than Hono's own `Next` (which is
+ * typed `Promise<void>`) so a forwarding middleware can `return next()` to
+ * propagate a downstream short-circuit without an unsafe cast.
+ */
+type Next = () => Promise<Response | void>;
+/**
+ * Middleware interface for request processing
+ *
+ * Middlewares use the `@Transient()` decorator and are registered via
+ * `configureRoutes(router)` in modules implementing `RouteConfigurable`.
+ *
+ * @example
+ * ```typescript
+ * @Transient()
+ * export class LoggingMiddleware implements Middleware {
+ *   async handle(ctx: RouterContext, next: Next): Promise<void> {
+ *     const start = Date.now()
+ *     await next()
+ *     console.log(`Request took ${Date.now() - start}ms`)
+ *   }
+ * }
+ *
+ * // Register in module:
+ * @Module({ providers: [LoggingMiddleware] })
+ * export class AppModule implements RouteConfigurable {
+ *   configureRoutes(router: Router): void {
+ *     router.middleware(LoggingMiddleware)
+ *   }
+ * }
+ * ```
+ */
+interface Middleware {
+  /**
+   * Handle middleware logic
+   * Call next() to continue the middleware chain
+   *
+   * @param ctx - Router context with request/response helpers
+   * @param next - Function to call the next middleware or route handler
+   */
+  handle(ctx: RouterContext, next: Next): Promise<Response | void>;
+}
+//#endregion
+//#region src/response-cache/types.d.ts
+/** Options accepted by `@Cacheable`. Every field is optional so module defaults can supply it. */
+interface CacheableOptions {
+  /** Freshness lifetime in seconds, emitted as `max-age`. */
+  ttl?: number;
+  /**
+   * How long a PRIVATE cache — a visitor's browser — may reuse the response
+   * without asking, in seconds. Defaults to {@link ttl}.
+   *
+   * Set it to `0` for a response whose retraction has to be reliable. A purge
+   * reaches the shared cache and nothing else, so for a long `ttl` a browser
+   * copy outlives the response the server has already withdrawn. Pair `0` with
+   * {@link swr} and the browser still paints from its copy without waiting on
+   * the network, then picks the retraction up in the background.
+   */
+  browserTtl?: number;
+  /** `stale-while-revalidate` window in seconds. */
+  swr?: number;
+  /** `Cache-Tag` values. Supports `{scope.path}` interpolation. Never defaulted at module level. */
+  tags?: string[];
+  /** Named partitions placed into `ctx.props`. An explicit `[]` declares the route public. */
+  partitionBy?: string[];
+  /** Additional `Vary` header names, unioned with module defaults. */
+  vary?: string[];
+}
+/** Options accepted by `@PurgesCache`. */
+interface PurgesCacheOptions {
+  tags?: string[];
+  pathPrefixes?: string[];
+  /** Exclusive — cannot be combined with `tags` or `pathPrefixes`. */
+  purgeEverything?: boolean;
+}
+/** A `@Cacheable` config after module defaults have been applied. */
+interface ResolvedCacheable {
+  ttl: number;
+  browserTtl: number;
+  swr?: number;
+  tags: string[];
+  partitionBy: string[];
+  vary: string[];
+}
+/**
+ * Resolves one named partition value for the current request.
+ *
+ * Runs in the gateway, after the primer chain, so `ctx.user()` and the
+ * request-scoped container are available. Returning `null` or `undefined`
+ * fails closed — the response is not cached.
+ */
+type PartitionResolver = (ctx: RouterContext) => string | null | undefined | Promise<string | null | undefined>;
+/**
+ * The `gateway.entrypoint` names derivable from a Worker's exports map.
+ *
+ * Drops `'default'`: the cached entrypoint is never the default export
+ * (`cachedEntrypoint` and the boot check both reject that), so naming it is
+ * always a mistake — one worth catching at compile time rather than on the
+ * first request after deploy. Non-string keys are dropped too.
+ *
+ * Degrades to `string` when the exports map is empty. That covers both a
+ * project that has not run `wrangler types` and the framework's own
+ * compilation, where `Cloudflare.Exports` is `{}` — neither should be blocked,
+ * and `resolveCachedEntrypoint` stays the runtime backstop for them.
+ *
+ * @typeParam Exports - a Worker's top-level exports, e.g. `Cloudflare.Exports`.
+ */
+type EntrypointNameFrom<Exports> = [Exclude<Extract<keyof Exports, string>, 'default'>] extends [never] ? string : Exclude<Extract<keyof Exports, string>, 'default'>;
+/**
+ * The names `gateway.entrypoint` accepts.
+ *
+ * In a consumer project that has run `wrangler types`, `Cloudflare.Exports` is
+ * populated from `Cloudflare.GlobalProps.mainModule`, so this resolves to the
+ * union of that Worker's real, non-default export names: a typo like `'Cachd'`
+ * is a compile error at the config site, not a `ResponseCacheConfigError` on
+ * the first request after deploy. Without generated types it is `string`.
+ */
+type CachedEntrypointName = EntrypointNameFrom<Cloudflare.Exports>;
+/**
+ * Names the cached entrypoint the gateway forwards partitioned reads to.
+ *
+ * The framework cannot discover the consumer's export name, so it is
+ * configured. It must match a top-level export built with
+ * `cachedEntrypoint(stratal)` from `stratal/workers`, and that export must be
+ * declared in the Wrangler `exports` block with `cache: { enabled: true }`
+ * while the default export has `cache: { enabled: false }`.
+ */
+interface ResponseCacheGatewayOptions {
+  /**
+   * e.g. `'Cached'` for `export const Cached = cachedEntrypoint(stratal)`.
+   *
+   * Typed as {@link CachedEntrypointName}: when `wrangler types` has generated
+   * `Cloudflare.Exports`, only this Worker's real, non-default export names are
+   * accepted, so a typo is caught by the type checker. It is still validated at
+   * runtime (`resolveCachedEntrypoint`) for projects without generated types.
+   */
+  entrypoint: CachedEntrypointName;
+  /**
+   * Request headers whose values join the cache key, for routes that answer
+   * one URL with more than one representation.
+   *
+   * `Vary` is the mechanism HTTP defines for this, and Workers Caching
+   * documents it as honoured — but a response that varies is only *correct*
+   * when the thing it varies on is in the key, and the key is the one part of
+   * this that the framework controls. `ctx.props` is documented as impossible
+   * to bypass; `Vary` is a request-matching pass on top of a stored entry, and
+   * a URL carrying a query string has been measured serving one
+   * representation to a request that asked for the other. Naming the headers
+   * here makes the representation part of the key itself, so two
+   * representations are two entries and no matching pass has to hold.
+   *
+   * For an Inertia app this is `INERTIA_VARY_HEADERS` from `@stratal/inertia`:
+   * the document, the visit and each distinct partial reload are separate
+   * representations of one URL.
+   *
+   * Anything a response declares in `Vary` that is not named here (or handled
+   * by the platform itself, as `Accept-Encoding` is) makes that response
+   * uncacheable rather than wrongly cacheable — see `CacheabilityService`.
+   */
+  keyBy?: readonly string[];
+}
+interface ResponseCacheModuleOptions {
+  /** Defaults applied to every `@Cacheable` route. `tags` is not defaultable. */
+  defaults?: Omit<CacheableOptions, 'tags'>;
+  /**
+   * The cached entrypoint partitioned reads are forwarded to.
+   *
+   * Required before any route may declare a non-empty `partitionBy`, and
+   * before `partitions`/`primers` may be configured — without it there is no
+   * way to place a partition in the cache key, and a route marked per-user
+   * that quietly shared one cache entry would serve one visitor's page to
+   * everyone.
+   */
+  gateway?: ResponseCacheGatewayOptions;
+  /**
+   * Named partition resolvers, referenced by `partitionBy`.
+   *
+   * Resolvers run in the gateway, after the primer chain, so `ctx.user()` and
+   * the request-scoped container are available. Requires `gateway`: without a
+   * cached entrypoint nothing would ever call them, so configuring them alone
+   * throws `ResponseCacheConfigError` at boot rather than reading as proof
+   * that per-user keying is in effect.
+   */
+  partitions?: Record<string, PartitionResolver>;
+  /**
+   * Middleware run in the gateway before partition resolution, so resolvers
+   * see the same context the app would.
+   *
+   * `@stratal/framework` exports `AUTH_GATEWAY_PRIMERS` for this — pass it to
+   * make `ctx.user()` resolve inside a partition resolver. Requires
+   * `gateway`, for the same reason `partitions` does.
+   */
+  primers?: readonly (new (...args: never[]) => Middleware)[];
+}
+//#endregion
+//#region src/response-cache/services/cacheability.service.d.ts
+/** Inertia-specific conditions that make a page unsafe to cache. */
+interface InertiaCacheSignals {
+  hasFlash: boolean;
+  isPartial: boolean;
+  hasOnceProps: boolean;
+  /**
+   * Request headers the adapter reports this response is a function of.
+   * Unioned into `Vary`, so a partial reload and the full page at the same URL
+   * are stored as separate variants rather than colliding.
+   *
+   * Required rather than optional: an empty list is what makes a partial reload
+   * fail closed, and an adapter that simply forgot the field would otherwise be
+   * indistinguishable from one declaring the response unkeyed.
+   */
+  varyHeaders: readonly string[];
+}
+interface CacheabilitySignals {
+  /** False when any declared partition resolver returned null/undefined. */
+  partitionsResolved: boolean;
+  inertia?: InertiaCacheSignals;
+}
+/**
+ * Decides whether a `@Cacheable` response may actually be cached, and stamps
+ * the headers that say so.
+ *
+ * Everything that is not provably safe becomes `private, no-store`. That
+ * matters more than it looks: Workers Caching applies RFC 9111 heuristic
+ * freshness, so a response with no `Cache-Control` at all is still cached —
+ * `200` for two hours. Silence is not a safe default here.
+ */
+declare class CacheabilityService {
+  private readonly logger;
+  private readonly options;
+  constructor(logger: LoggerService, options: ResponseCacheModuleOptions);
+  apply(response: Response, resolved: ResolvedCacheable, scopes: TagScopes, signals: CacheabilitySignals): Response;
+  /** The first condition that makes this response unsafe to cache, if any. */
+  private rejectionReason;
+  /**
+   * What a PRIVATE cache — a visitor's browser — may do with the response.
+   *
+   * A browser copy is the one this feature cannot reach: `Cache-Tag` and
+   * `ctx.cache.purge()` retire the shared copy, and nothing retires that one.
+   * So `browserTtl` is what a route says it is willing to have held without
+   * being askable, and it defaults to `ttl` — the same lifetime the shared
+   * cache was already given.
+   *
+   * `stale-while-revalidate` is emitted here as well as on the shared header,
+   * and it is what makes a short `browserTtl` cheap rather than punishing: the
+   * browser paints from the copy it has instead of waiting on the network, and
+   * fetches the replacement behind that. A route that must be retractable sets
+   * `browserTtl: 0` with a stale window, and converges on the next navigation
+   * rather than holding a withdrawn response for the whole `ttl`.
+   *
+   * `must-revalidate` only where there is no stale window to protect: it
+   * forbids serving stale at all, which is the opposite of what `swr` asks
+   * for, so emitting both would leave the pair contradicting each other.
+   */
+  private browserCacheControl;
+  /** The lifetime, for the cache that can be purged. */
+  private sharedCacheControl;
+  /** Union the declared Vary names with whatever the response already set. */
+  private mergeVary;
+  /**
+   * Overlay headers onto the response, mutating in place when the header
+   * list is writable — see `setResponseHeaders` for why that's the common
+   * case and safe. `Cache-Tag` and `CDN-Cache-Control` are explicitly deleted
+   * (not just omitted) when degrading to `no-store`, so neither a stale tag
+   * nor a lifetime from a differently-decided response lingers. The second
+   * matters most: Cloudflare reads `CDN-Cache-Control` in preference to
+   * `Cache-Control`, so one left behind would cache a response this just
+   * refused to cache.
+   */
+  private withHeaders;
+}
+//#endregion
 //#region src/router/constants.d.ts
 /**
  * Type-safe context keys for Hono router variables
  * Using symbols to avoid string collisions
  */
 declare const ROUTER_CONTEXT_KEYS: {
-  readonly REQUEST_CONTAINER: "requestContainer";
-  readonly LOCALE: "locale";
+  readonly REQUEST_CONTAINER: 'requestContainer';
+  readonly LOCALE: 'locale';
+  readonly RESPONSE_PAYLOAD: 'responsePayload';
 };
 /**
  * Metadata keys for storing route and controller configuration
@@ -163,15 +483,17 @@ declare const ROUTE_METADATA_KEYS: {
   readonly WS_ON_CLOSE: symbol;
   readonly WS_ON_ERROR: symbol;
   readonly RATE_LIMIT: symbol;
+  readonly CACHEABLE: symbol;
+  readonly PURGES_CACHE: symbol;
 };
 /**
  * Security scheme identifiers for OpenAPI
  * These reference the security scheme definitions in security.schemas.ts
  */
 declare const SECURITY_SCHEMES: {
-  readonly BEARER_AUTH: "bearerAuth";
-  readonly API_KEY: "apiKey";
-  readonly SESSION_COOKIE: "sessionCookie";
+  readonly BEARER_AUTH: 'bearerAuth';
+  readonly API_KEY: 'apiKey';
+  readonly SESSION_COOKIE: 'sessionCookie';
 };
 /**
  * HTTP method mapping for RESTful controller methods
@@ -179,28 +501,28 @@ declare const SECURITY_SCHEMES: {
  */
 declare const HTTP_METHODS: {
   readonly index: {
-    readonly method: "get";
-    readonly path: "";
+    readonly method: 'get';
+    readonly path: '';
   };
   readonly show: {
-    readonly method: "get";
-    readonly path: "/:id";
+    readonly method: 'get';
+    readonly path: '/:id';
   };
   readonly create: {
-    readonly method: "post";
-    readonly path: "";
+    readonly method: 'post';
+    readonly path: '';
   };
   readonly update: {
-    readonly method: "put";
-    readonly path: "/:id";
+    readonly method: 'put';
+    readonly path: '/:id';
   };
   readonly patch: {
-    readonly method: "patch";
-    readonly path: "/:id";
+    readonly method: 'patch';
+    readonly path: '/:id';
   };
   readonly destroy: {
-    readonly method: "delete";
-    readonly path: "/:id";
+    readonly method: 'delete';
+    readonly path: '/:id';
   };
 };
 /**
@@ -211,10 +533,10 @@ declare const VERSION_NEUTRAL: unique symbol;
 //#endregion
 //#region src/router/types.d.ts
 /**
- * Route parameter type for OpenAPI
- * ZodObject or ZodPipe (piped validation)
+ * Route parameter type — a Zod object schema (its `.shape` is composed with
+ * router-prefix params at registration).
  */
-type ZodObjectWithEffect = zod_d_exports.ZodObject<any> | zod_d_exports.ZodPipe<any, any>;
+type ZodObjectWithEffect = ZodObject<any>;
 type RouteParameter = ZodObjectWithEffect | undefined;
 /**
  * Hono context variables with type-safe keys
@@ -223,9 +545,28 @@ interface RouterVariables {
   [ROUTER_CONTEXT_KEYS.REQUEST_CONTAINER]: Container;
   [ROUTER_CONTEXT_KEYS.LOCALE]?: string;
   /**
-   * When set by middleware, the defaultHook returns this response after
-   * successful validation — skipping the controller handler entirely.
-   * Used by packages like `@stratal/inertia` for precognition support.
+   * The handler's captured JSON payload, set by `capturePayload()` so
+   * `{data.*}` response-cache tag templates can read values the request
+   * itself never carried. Only populated for routes that declared a tag
+   * needing it — see `needsPayloadCapture`.
+   */
+  [ROUTER_CONTEXT_KEYS.RESPONSE_PAYLOAD]?: unknown;
+  /**
+   * Cache safety signals for the page rendered on this request, set by
+   * `@stratal/inertia`'s `InertiaService.render()`. Read by
+   * `RouteRegistrationService.applyCacheDecision()` and passed to
+   * `CacheabilityService.apply()` so a `@Cacheable` route serving an Inertia
+   * page with flash data, a partial reload, or once-props fails closed
+   * instead of caching and replaying it. Declared here (not imported from
+   * `@stratal/inertia`) so core never depends on that package — the key is
+   * only ever populated when `@stratal/inertia` is in use.
+   */
+  inertiaCacheSignals?: InertiaCacheSignals;
+  /**
+   * When set by middleware, the route handler returns this response instead of
+   * invoking the controller — skipping the handler entirely once request
+   * validators have passed. Used by packages like `@stratal/inertia` for
+   * precognition support.
    */
   validationSuccessResponse?: Response;
   /** Domain parameters set by the domain matching middleware (e.g., `domain:tenant`) */
@@ -247,23 +588,28 @@ type SecurityScheme = typeof SECURITY_SCHEMES[keyof typeof SECURITY_SCHEMES];
  * HTTP method type from OpenAPI spec
  */
 type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head' | 'options' | 'trace' | 'all';
+/**
+ * Security scheme record for OpenAPI security array format
+ * Maps scheme names to scopes (empty array for no scopes)
+ */
+type SecuritySchemeRecord = Record<SecurityScheme, string[]>;
 /**
  * Object form for request body with optional content type
  */
 interface RouteBodyObject {
-  schema: zod_d_exports.ZodType;
+  schema: ZodType;
   contentType?: string;
 }
 /**
  * Request body definition for @Route() decorator
  * Bare ZodType defaults to application/json
  */
-type RouteBody = zod_d_exports.ZodType | RouteBodyObject;
+type RouteBody = ZodType | RouteBodyObject;
 /**
  * Object form for response with optional description and content type
  */
 interface RouteResponseObject {
-  schema: zod_d_exports.ZodType;
+  schema: ZodType;
   description?: string;
   contentType?: string;
 }
@@ -271,7 +617,7 @@ interface RouteResponseObject {
  * Single response definition for @Route() decorator
  * Status code is auto-derived from method name (create->201, others->200)
  */
-type RouteResponse = zod_d_exports.ZodType | RouteResponseObject;
+type RouteResponse = ZodType | RouteResponseObject;
 /**
  * Route configuration for @Route() decorator
  * Defines OpenAPI metadata for a controller method
@@ -279,11 +625,11 @@ type RouteResponse = zod_d_exports.ZodType | RouteResponseObject;
 interface RouteConfig {
   /**
    * Request body schema (for POST, PUT, PATCH)
-   * @example z.object({}) or { schema: z.object({}), contentType: 'multipart/form-data' }
+   * @example object({}) or { schema: object({}), contentType: 'multipart/form-data' }
    */
   body?: RouteBody;
   /**
-   * URL parameters schema (e.g., { id: z.string().uuid() })
+   * URL parameters schema (e.g., object({ id: uuid() }))
    * Must be ZodObject or ZodPipe for OpenAPI compatibility
    */
   params?: RouteParameter;
@@ -309,6 +655,11 @@ interface RouteConfig {
    * Empty array = public route (no auth)
    */
   security?: SecurityScheme[];
+  /**
+   * Visibility group labels for this route.
+   * Appended to the controller-level groups.
+   */
+  groups?: string[];
   /**
    * Human-readable description for OpenAPI docs
    */
@@ -377,6 +728,11 @@ interface ControllerOptions {
    * Routes can add more schemes or override with empty array
    */
   security?: SecurityScheme[];
+  /**
+   * Default visibility group labels applied to every route in this controller.
+   * Routes append more via the route-level `groups`.
+   */
+  groups?: string[];
   /**
    * Hide all routes in this controller from OpenAPI documentation
    * Routes remain functional but won't appear in /api/docs or /api/openapi.json
@@ -492,8 +848,58 @@ interface LocaleUrlConfig {
 }
 //#endregion
 //#region src/execution-context.d.ts
+/** A purge request in the shape `ctx.cache.purge()` accepts. */
+interface PurgeSpec {
+  tags?: string[];
+  pathPrefixes?: string[];
+  purgeEverything?: true;
+}
+/**
+ * The subset of Cloudflare's Workers Caching API (`ctx.cache`) Stratal uses.
+ *
+ * Declared here rather than under `response-cache/` so the dependency points
+ * from the feature to this foundational module, not the reverse — describing
+ * the shape of an execution context should not require knowing about a
+ * feature. `stratal/response-cache` re-exports both types, so consumers still
+ * import them from there.
+ */
+interface WorkersCache {
+  purge(spec: PurgeSpec): Promise<{
+    success: boolean;
+  } | void>;
+}
 interface StratalExecutionContext {
   waitUntil(promise: Promise<unknown>): void;
+  /**
+   * The Cloudflare Workers Caching API (`ctx.cache`). Optional because
+   * Wrangler only attaches it when `cache.enabled: true` is configured — see
+   * `cachingUnavailableReason`, which reports why `@Cacheable`/`@PurgesCache`
+   * routes are serving uncached when this is absent.
+   *
+   * Declared here (rather than left for call sites to cast onto their own
+   * narrower `ExecutionContext`) so `@stratal/testing` can populate a stub on
+   * the same object it hands to `Application` and to `HonoApp#fetch`, making
+   * cache-decorated routes testable without a real Workers Caching binding.
+   */
+  cache?: WorkersCache;
+  /**
+   * Loopback bindings to the Worker's own top-level exports (`ctx.exports`),
+   * available with the `enable_ctx_exports` compatibility flag.
+   *
+   * `stratal/response-cache`'s gateway forwards partitioned reads through
+   * this, so it is declared here for the same reason `cache` is: so
+   * `@stratal/testing` can populate a stub on the object it hands to
+   * `Application` and `HonoApp#fetch`. Typed loosely because the shape of any
+   * one binding depends on the consumer's own exports, which the framework
+   * cannot know — see `resolveCachedEntrypoint`, which checks it at runtime.
+   */
+  exports?: Record<string, unknown>;
+  /**
+   * The `ctx.props` the caller chose for this invocation. Wholly part of the
+   * Workers Caching cache key, which is what makes per-caller partitioning
+   * safe. Set by the gateway when it dispatches; never read by the framework.
+   */
+  props?: unknown;
 }
 //#endregion
 //#region src/di/lazy.d.ts
@@ -694,56 +1100,20 @@ interface IController {
   handle?(ctx: RouterContext): Promise<Response> | Response;
 }
 //#endregion
-//#region src/router/middleware.interface.d.ts
-type Next$1 = Next;
-/**
- * Middleware interface for request processing
- *
- * Middlewares use the `@Transient()` decorator and are registered via
- * `configureRoutes(router)` in modules implementing `RouteConfigurable`.
- *
- * @example
- * ```typescript
- * @Transient()
- * export class LoggingMiddleware implements Middleware {
- *   async handle(ctx: RouterContext, next: () => Promise<void>): Promise<void> {
- *     const start = Date.now()
- *     await next()
- *     console.log(`Request took ${Date.now() - start}ms`)
- *   }
- * }
- *
- * // Register in module:
- * @Module({ providers: [LoggingMiddleware] })
- * export class AppModule implements RouteConfigurable {
- *   configureRoutes(router: Router): void {
- *     router.middleware(LoggingMiddleware)
- *   }
- * }
- * ```
- */
-interface Middleware {
-  /**
-   * Handle middleware logic
-   * Call next() to continue the middleware chain
-   *
-   * @param ctx - Router context with request/response helpers
-   * @param next - Function to call the next middleware or route handler
-   */
-  handle(ctx: RouterContext, next: Next$1): Promise<Response | void>;
-}
-//#endregion
 //#region src/router/hono-app.d.ts
 /**
- * HonoApp — extends OpenAPIHono with Stratal-specific setup
+ * HonoApp — extends plain Hono with Stratal-specific setup
  *
  * - Request scope middleware (child container per request)
  * - Global middleware (CORS, logging, error handling)
- * - defaultHook for validation errors
  * - `use()` overload for Stratal middleware classes
  * - `configure()` for OpenAPI, routes, and 404
+ *
+ * Request validation is attached per-route via `hono/validator` middleware (see
+ * route-registration), not a base-class hook, so schema-less routes pull in no
+ * validation/zod code.
  */
-declare class HonoApp extends OpenAPIHono<RouterEnv> {
+declare class HonoApp extends Hono<RouterEnv> {
   private configured;
   private readonly _container;
   private readonly _logger;
@@ -768,6 +1138,177 @@ declare class HonoApp extends OpenAPIHono<RouterEnv> {
   private handleException;
 }
 //#endregion
+//#region src/i18n/i18n.options.d.ts
+/**
+ * Detection strategy for locale resolution
+ *
+ * - `'cookie'` — reads from the `locale` cookie (default)
+ * - `'header'` — reads from the `Accept-Language` header
+ * - `'querystring'` — reads from the `?locale=` query parameter
+ * - `'path'` — reads from the first URL path segment (e.g., `/en/api/users`)
+ */
+type DetectionStrategy = 'cookie' | 'header' | 'querystring' | 'path';
+/** The cookie (and query-string key) the `locale` is read from / written to. */
+declare const LOCALE_COOKIE = "locale";
+interface BaseDetection {
+  /** Set to false to disable language detection entirely. @default true */
+  enabled?: boolean;
+}
+/**
+ * Language detection options (discriminated by strategy)
+ *
+ * @example Cookie detection (default)
+ * ```typescript
+ * { strategy: 'cookie' }
+ * ```
+ *
+ * @example Header detection
+ * ```typescript
+ * { strategy: 'header' }
+ * ```
+ *
+ * @example Path detection
+ * ```typescript
+ * { strategy: 'path' }
+ * ```
+ *
+ * @example Disable detection
+ * ```typescript
+ * { enabled: false }
+ * ```
+ */
+type LanguageDetectionOptions = (BaseDetection & {
+  strategy?: 'cookie';
+  cookieOptions?: DetectorOptions['cookieOptions'];
+}) | (BaseDetection & {
+  strategy: 'header';
+}) | (BaseDetection & {
+  strategy: 'querystring';
+}) | (BaseDetection & {
+  strategy: 'path';
+  /**
+   * Controls whether the default locale gets a URL path prefix.
+   *
+   * - `false` (default) — The default locale has no prefix (`/users`), other locales
+   *   are prefixed (`/fr/users`). Requests to the prefixed default locale (`/en/users`) return 404.
+   * - `'redirect'` — Same as `false`, but requests to the prefixed default locale
+   *   (`/en/users`) are 301-redirected to the unprefixed path (`/users`).
+   * - `true` — All locales are prefixed (`/en/users`, `/fr/users`).
+   *
+   * @default false
+   */
+  prefixDefaultLocale?: false | true | 'redirect';
+}) | {
+  enabled: false;
+};
+/**
+ * A per-path detection resolver.
+ *
+ * Returns the detection options for a given request path. It **must be a pure
+ * function of the path**: route `/:locale` variant expansion runs it at boot,
+ * once per registered route pattern, where no request exists — so the decision
+ * (e.g. "`/admin` is cookie-localized, everything else is path-localized") has
+ * to be derivable from the path alone, and must agree at boot and per request.
+ *
+ * @example
+ * ```typescript
+ * detection: (path) =>
+ *   path.startsWith('/admin')
+ *     ? { strategy: 'cookie', cookieOptions: { path: '/admin' } }
+ *     : { strategy: 'path' }
+ * ```
+ */
+type DetectionResolver = (path: string) => LanguageDetectionOptions;
+/** Detection config: a single static option set, or a per-path resolver. */
+type DetectionConfig = LanguageDetectionOptions | DetectionResolver;
+/**
+ * Options for configuring the I18n module
+ *
+ * @example
+ * ```typescript
+ * I18nModule.forRoot({
+ *   defaultLocale: 'en',
+ *   fallbackLocale: 'en',
+ *   locales: ['en', 'fr'],
+ *   detection: { strategy: 'header' },
+ * })
+ * ```
+ */
+interface I18nModuleOptions {
+  /**
+   * Default locale for the application
+   * @default 'en'
+   */
+  defaultLocale?: string;
+  /**
+   * Fallback locale when translation is missing
+   * @default 'en'
+   */
+  fallbackLocale?: string;
+  /**
+   * List of supported locales
+   * Request locales not in this list will fall back to defaultLocale
+   */
+  locales?: string[];
+  /**
+   * Language detection configuration. Either a single option set applied to
+   * every request, or a {@link DetectionResolver} — a pure function of the
+   * request path — so different areas can use different strategies (e.g. a
+   * path-localized public site with a cookie-localized `/admin` panel).
+   */
+  detection?: DetectionConfig;
+}
+/**
+ * Detection options resolved for a single path (all defaults applied).
+ */
+interface ResolvedDetection {
+  enabled: boolean;
+  strategy: DetectionStrategy;
+  /** Only meaningful when `strategy` is `'path'`. */
+  prefixDefaultLocale: false | true | 'redirect';
+  /**
+   * Cookie attributes for the persisted `locale` cookie under cookie strategy
+   * (e.g. `{ path: '/admin' }` to scope a panel's locale so it isn't written at
+   * the default `Path=/`).
+   */
+  cookieOptions?: DetectorOptions['cookieOptions'];
+}
+/**
+ * Resolved options with all defaults applied
+ * Used internally by I18n services
+ */
+interface ResolvedI18nOptions {
+  defaultLocale: string;
+  fallbackLocale: string;
+  locales: string[];
+  /**
+   * Detection resolved at the application root (`/`) — the app's primary mode.
+   * For per-path detail (when `detection` is a resolver) use
+   * {@link resolveDetectionForPath}.
+   */
+  detection: ResolvedDetection;
+}
+/**
+ * Resolve the detection options for a given request path, evaluating the
+ * per-path resolver when `detection` is a function.
+ */
+declare function resolveDetectionForPath(detection: DetectionConfig | undefined, path: string): ResolvedDetection;
+/**
+ * Resolve I18n options with defaults. `detection` reflects the application root
+ * (`/`); use {@link resolveDetectionForPath} for per-path detail.
+ */
+declare function resolveI18nOptions(options?: I18nModuleOptions): ResolvedI18nOptions;
+/**
+ * Build Hono languageDetector options for a resolved detection + locale config.
+ *
+ * Cookie strategy persists the detected locale to the `locale` cookie
+ * (`caches: ['cookie']`) using the resolved `cookieOptions` — so a per-path
+ * cookie area scopes the write (e.g. `{ path: '/admin' }`) instead of writing
+ * at the default `Path=/` and leaking across the app. Other strategies don't
+ * write any cookie.
+ */
+declare function buildDetectorOptions(detection: ResolvedDetection, locales: string[], defaultLocale: string): Partial<DetectorOptions>;
+//#endregion
 //#region src/router/services/locale-path.service.d.ts
 /**
  * A resolved path with locale variant metadata.
@@ -781,48 +1322,59 @@ interface ResolvedPath {
 /**
  * Resolves locale path variants for route paths.
  *
- * Computes `LocalePathConfig` from `I18nModuleOptions` and provides
- * path expansion for locale-prefixed route variants.
- *
- * Also applies language detection and default locale redirect middleware
- * to HonoApp when resolved from the container.
+ * Detection can be static or a per-path resolver (see {@link DetectionConfig}),
+ * so this evaluates it **per path**: which routes get a `/:locale` variant
+ * (at registration) and which detector runs (per request). A path resolving to
+ * a non-`path` strategy gets no variant and is localized out-of-band (cookie).
  *
- * Registered as a singleton in the container.
+ * Also applies language detection and default-locale redirect middleware to
+ * HonoApp when resolved from the container. Registered as a singleton.
  */
 declare class LocalePathService {
   private readonly honoApp;
-  private readonly _config;
-  private readonly _pathDetectionEnabled;
-  private readonly _prefixDefaultLocale;
+  private readonly _locales;
+  private readonly _defaultLocale;
+  private readonly _detection;
+  /** Detection + config resolved at the application root (`/`) — the primary mode. */
+  private readonly _primary;
+  private readonly _primaryConfig;
   constructor(container: Container, honoApp: HonoApp);
-  /** Whether path-based locale detection is enabled */
+  /** Whether the app uses path-based locale URLs (resolved at the root). */
   get enabled(): boolean;
-  /** The computed locale path config, or null if path detection is disabled */
+  /** The primary (root) locale path config, or null if the root isn't path-localized. */
   get localePathConfig(): LocalePathConfig | null;
-  /** The prefixDefaultLocale setting (false, true, or 'redirect') */
+  /** The primary (root) prefixDefaultLocale setting (false, true, or 'redirect'). */
   get prefixDefaultLocale(): false | true | 'redirect';
+  /** Resolve the detection options for a given request path. */
+  detectionFor(path: string): ResolvedDetection;
+  /**
+   * Whether a pathname is path-localized — served with a `/:locale` segment.
+   * `false` for paths resolving to a non-`path` strategy (localized by cookie)
+   * or with detection disabled. Redirect middleware should skip non-localized
+   * paths so it never prepends a locale segment.
+   */
+  isPathLocalized(pathname: string): boolean;
   /**
    * Expand a path into primary + locale-prefixed variants.
    *
-   * @param path - The base path to expand
+   * @param path - The base route path to expand
    * @returns Array of resolved paths with locale metadata
    */
   resolve(path: string): ResolvedPath[];
+  /** Build the locale path config for a resolved detection, or null if not path-localized. */
+  private buildConfig;
   /**
-   * Build a Hono regex constraint from prefixed locales.
-   * e.g., `{en|de|fr}` — restricts `:locale` to only match known values.
-   */
-  private buildLocaleConstraint;
-  /**
-   * Apply Hono's languageDetector middleware and bridge the detected language
-   * to Stratal's LOCALE context variable.
+   * Apply Hono's languageDetector and bridge the detected language to Stratal's
+   * LOCALE context variable. With a per-path resolver, the detector is chosen
+   * per request (cached by strategy); with a static config, one detector is
+   * built up front.
    */
   private setupLanguageDetection;
   /**
    * Redirect requests that include the default locale prefix to the unprefixed path.
    * For example, `/en/users` → 301 redirect to `/users`.
    *
-   * Only active when `prefixDefaultLocale` is `'redirect'`.
+   * Only active when the root `prefixDefaultLocale` is `'redirect'`.
    */
   private setupDefaultLocaleRedirect;
 }
@@ -849,6 +1401,13 @@ declare class LocaleUrlService {
   applyPrefix(pathname: string, locale: string): string;
   /** Strip a known-locale prefix from the start of a pathname. */
   stripPrefix(pathname: string): string;
+  /**
+   * Whether a pathname is path-localized — served with a `/:locale` segment.
+   * `false` for paths localized out-of-band (cookie strategy) or with detection
+   * disabled. Redirect middleware should skip non-localized paths so it never
+   * prepends a locale segment to a path that isn't path-localized.
+   */
+  isPathLocalized(pathname: string): boolean;
   private toUrlConfig;
 }
 //#endregion
@@ -860,8 +1419,9 @@ declare class LocaleUrlService {
  * Only internal modules (RouterResolver) import them, keeping the Router's
  * public API clean — users never see these methods.
  *
- * Declared as individual unique symbols so TypeScript can distinguish
- * their return types in computed property access.
+ * Registered via `Symbol.for` so that a duplicate evaluation of this module
+ * (e.g. under a bundler or SSR module runner) resolves to the same symbol,
+ * keeping symbol-keyed dispatch between `Router` and `RouterResolver` stable.
  *
  * @internal
  */
@@ -883,7 +1443,7 @@ interface RouterGroupConfig {
   middleware?: Constructor<Middleware>[];
   version?: string | string[];
   hideFromDocs?: boolean;
-  params?: zod_d_exports.ZodObject<any>;
+  params?: ZodObject<any>;
 }
 /**
  * Internal entry representing a sub-group or the default scope.
@@ -896,7 +1456,7 @@ interface RouterEntry {
   middleware: Constructor<Middleware>[];
   version?: string | string[];
   hideFromDocs?: boolean;
-  params?: zod_d_exports.ZodObject<any>;
+  params?: ZodObject<any>;
   /** Controllers in this entry. undefined = all controllers not in any sub-group */
   controllers?: Constructor[];
 }
@@ -939,7 +1499,7 @@ declare class Router {
   private readonly _globalMiddleware;
   constructor(isChild?: boolean);
   /** Dynamic path prefix. For shared segments like `/:companyId` */
-  prefix(path: string, params?: zod_d_exports.ZodObject<any>): this;
+  prefix(path: string, params?: ZodObject<any>): this;
   /** Domain pattern for controllers in this scope */
   domain(pattern: string): this;
   /** Name prefix for routes in this scope */
@@ -1050,6 +1610,122 @@ declare class ModuleRegistry {
   private collectIfListener;
 }
 //#endregion
+//#region src/response-cache/services/gateway-route-table.d.ts
+/**
+ * What the dispatch middleware needs to know about one route.
+ *
+ * Typed as a `CacheableOptions` (every field optional) rather than a bespoke
+ * shape so it can be handed straight to `shouldLoopback`, which already
+ * encodes "only GET/HEAD ever loop back".
+ */
+interface GatewayRouteEntry extends CacheableOptions {
+  partitionBy: string[];
+}
+/**
+ * `${METHOD} ${routePath}` → the partitions that route declared.
+ *
+ * Populated once, at route registration, and only for routes whose
+ * **effective** `partitionBy` (after module defaults) is non-empty. Every
+ * other route is absent, and absence means "run inline" — the safe default,
+ * and the one that keeps an app which uses no partitions paying nothing but a
+ * single `isEmpty` check per request.
+ *
+ * The key is the route *pattern* Hono matched (`/posts/:id`), not the request
+ * path, so one entry serves every request to that route.
+ */
+declare class GatewayRouteTable {
+  private readonly entries;
+  /**
+   * The consumer's `export const <name> = cachedEntrypoint(stratal)`, from
+   * `ResponseCacheModule.forRoot({ gateway: { entrypoint } })`.
+   *
+   * `undefined` means no gateway is configured, which is also the condition
+   * under which `bindRouteCache` refuses a non-empty `partitionBy` — so an
+   * unconfigured table is always an empty one.
+   */
+  entrypoint: string | undefined;
+  /**
+   * `gateway.keyBy` — the request headers whose values join the cache key.
+   *
+   * Carried here rather than resolved per request because the dispatch
+   * middleware already memoises this table, so reading it costs a property
+   * access on the hot path instead of a container lookup.
+   */
+  keyBy: readonly string[];
+  /** Set by `RouteRegistrationService.configure()`, before any request. */
+  configure(entrypoint: string | undefined, keyBy?: readonly string[]): void;
+  /** True when no route in this app declares a partition. */
+  get isEmpty(): boolean;
+  /** Number of recorded routes. Test/diagnostic affordance. */
+  get size(): number;
+  /**
+   * Record one registered route.
+   *
+   * `method` is the Hono-registered method; `path` is the pattern the route
+   * was registered under (already expanded for versioning and locale
+   * variants, so each variant gets its own entry).
+   */
+  record(method: string, path: string, partitionBy: string[]): void;
+  /** The entry for a matched route pattern, or `undefined` to run inline. */
+  lookup(method: string, path: string): GatewayRouteEntry | undefined;
+}
+//#endregion
+//#region src/response-cache/services/partition-resolver.service.d.ts
+interface PartitionResult {
+  /** Values to place in `ctx.props`. Empty when nothing resolved. */
+  props: Record<string, string>;
+  /** False when any declared partition could not be resolved — do not cache. */
+  resolved: boolean;
+}
+/**
+ * Resolves the named partitions a route declared into `ctx.props` values.
+ *
+ * `ctx.props` is part of the Workers Caching cache key and, per Cloudflare,
+ * "cannot be bypassed" — so this is what keeps one caller's cached response
+ * from reaching another.
+ */
+declare class PartitionResolverService {
+  private readonly options;
+  private readonly logger;
+  constructor(options: ResponseCacheModuleOptions, logger: LoggerService);
+  /** Throw at boot if a route names a partition with no registered resolver. */
+  assertKnown(names: string[], where: string): void;
+  /**
+   * Partition names seen so far, split by whether they have ever resolved.
+   *
+   * A resolver that fails is ordinary traffic — an anonymous visitor to a
+   * per-user route — so the per-request signal stays at `debug`. But a
+   * partition that has *never* resolved is a configuration mistake, not
+   * traffic: the usual cause is `partitions: { user: (ctx) => ctx.user().id }`
+   * configured without `primers: AUTH_GATEWAY_PRIMERS`, so `ctx.user()` throws
+   * on every request and the route is silently never cached. Warned once per
+   * name, so that diagnosis is available without making normal misses noisy.
+   */
+  private readonly warnedUnresolved;
+  private readonly everResolved;
+  private noteUnresolved;
+  resolve(ctx: RouterContext, names: string[]): Promise<PartitionResult>;
+}
+//#endregion
+//#region src/response-cache/services/response-cache.service.d.ts
+declare class ResponseCacheService {
+  private readonly logger;
+  constructor(logger: LoggerService);
+  /** Render a `@PurgesCache` declaration against this request's scopes. */
+  buildPurgeSpec(options: PurgesCacheOptions, scopes: TagScopes): PurgeSpec;
+  /**
+   * Issue a purge and wait for it.
+   *
+   * Deliberately not deferred through `waitUntil`: a client that re-reads
+   * immediately after its own write must not be served the pre-write response.
+   *
+   * @throws {CachePurgeError} The mutation has already committed at this point,
+   *   so failing loudly is the lesser evil against a cache that is silently
+   *   inconsistent with the database.
+   */
+  purge(spec: PurgeSpec, cache: WorkersCache): Promise<void>;
+}
+//#endregion
 //#region src/router/services/versioning.service.d.ts
 /**
  * Resolves version prefixes for route paths.
@@ -1110,9 +1786,13 @@ interface RegisteredRoute {
  * and expands versioned/locale paths via injected services.
  */
 type RouteRegistrationInput = Omit<RegisteredRoute, 'paramNames' | 'domainParamNames' | 'path' | 'localePaths' | 'isLocaleVariant'> & {
-  /** Base path before versioning/locale expansion */basePath: string; /** Version from controller/router config (used by VersioningService). Accepts VERSION_NEUTRAL symbol. */
-  version?: string | string[] | typeof VERSION_NEUTRAL; /** Pre-computed param names (optional, auto-extracted if omitted) */
-  paramNames?: string[]; /** Pre-computed domain param names (optional, auto-extracted if omitted) */
+  /** Base path before versioning/locale expansion */
+  basePath: string;
+  /** Version from controller/router config (used by VersioningService). Accepts VERSION_NEUTRAL symbol. */
+  version?: string | string[] | typeof VERSION_NEUTRAL;
+  /** Pre-computed param names (optional, auto-extracted if omitted) */
+  paramNames?: string[];
+  /** Pre-computed domain param names (optional, auto-extracted if omitted) */
   domainParamNames?: string[];
 };
 /**
@@ -1170,7 +1850,7 @@ interface ResolvedRouterConfig {
   middleware: Constructor<Middleware>[];
   version?: string | string[];
   hideFromDocs?: boolean;
-  params?: zod_d_exports.ZodObject<any>;
+  params?: ZodObject<any>;
 }
 /**
  * Internal resolver that computes the effective Router config for each controller.
@@ -1210,6 +1890,68 @@ declare class RouterResolver {
   private concatNames;
 }
 //#endregion
+//#region src/router/route-metadata.d.ts
+/** A single response declaration for a route, keyed by status code. */
+interface RouteResponseMeta {
+  status: number;
+  /** Absent for empty responses (e.g. 204); present for typed JSON responses. */
+  schema?: ZodType;
+  contentType: string;
+  description: string;
+}
+/**
+ * Schema + documentation metadata for one registered route. Collected at
+ * registration time and consumed lazily by the OpenAPI generator. Holds Zod
+ * schema *instances* (never imports `zod` itself) so a route with no schemas
+ * contributes none and pulls in no validation code.
+ */
+interface RouteSchemaMeta {
+  method: Exclude<HttpMethod, 'all'>;
+  /** Clean OpenAPI path with `{param}` placeholders and regex constraints stripped. */
+  path: string;
+  /** Hidden routes are still registered (for access control) but excluded from the doc. */
+  hidden: boolean;
+  tags: string[];
+  security: SecuritySchemeRecord[];
+  summary?: string;
+  description?: string;
+  request: {
+    params?: ZodType;
+    query?: ZodType;
+    body?: {
+      schema: ZodType;
+      contentType: string;
+    };
+  };
+  responses: RouteResponseMeta[];
+  /**
+   * Localized variant: the `locale` path segment to document as an enum. The
+   * value set is carried as plain strings so the generator emits the enum
+   * without constructing a Zod schema on the hot path.
+   */
+  localeParam?: {
+    name: string;
+    values: string[];
+  };
+  /**
+   * Visibility group labels for this route, resolved from the controller's and
+   * route's `groups` options. Absent when none are declared.
+   */
+  groups?: string[];
+  /** Extensible metadata bag for downstream packages. */
+  meta?: Record<string, unknown>;
+}
+/**
+ * Stratal-owned registry of route schema metadata. Replaces writes to
+ * `@hono/zod-openapi`'s internal `openAPIRegistry`: route registration pushes
+ * entries here, and the OpenAPI generator reads them on demand.
+ */
+declare class RouteMetadataRegistry {
+  private readonly entries;
+  add(entry: RouteSchemaMeta): void;
+  all(): readonly RouteSchemaMeta[];
+}
+//#endregion
 //#region src/router/services/route-registration.service.d.ts
 /**
  * Route registration service
@@ -1233,9 +1975,60 @@ declare class RouteRegistrationService {
   private localePathService;
   private app;
   private moduleRegistry;
+  private metadataRegistry;
+  private cacheability?;
+  private responseCache?;
+  private responseCacheOptions?;
+  private gatewayRouteTable?;
+  private partitionResolver?;
   private controllerClasses;
   private upgradeWebSocketFn;
-  constructor(logger: LoggerService, registry: RouteRegistry, routerResolver: RouterResolver | null, localePathService: LocalePathService, app: HonoApp, moduleRegistry: ModuleRegistry);
+  private cacheableRouteCount;
+  /**
+   * 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.
+   */
+  private cachingAvailability;
+  constructor(logger: LoggerService, registry: RouteRegistry, routerResolver: RouterResolver | null, localePathService: LocalePathService, app: HonoApp, moduleRegistry: ModuleRegistry, metadataRegistry: RouteMetadataRegistry, cacheability?: CacheabilityService | undefined, responseCache?: ResponseCacheService | undefined, responseCacheOptions?: ResponseCacheModuleOptions | undefined, gatewayRouteTable?: GatewayRouteTable | undefined, partitionResolver?: PartitionResolverService | undefined);
+  /**
+   * 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.
+   */
+  private gatewayEntrypoint;
+  /** `gateway.keyBy`, read under the same `forRootAsync` caveat as the entrypoint. */
+  private gatewayKeyBy;
+  /**
+   * `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.
+   */
+  private responseCacheDefaults;
   /**
    * Configure router with controllers and global middleware.
    * Resolves controllers from ModuleRegistry and global middleware from RouterResolver.
@@ -1295,14 +2088,20 @@ declare class RouteRegistrationService {
    */
   private mergeMetadata;
   /**
-   * Build OpenAPI route configuration from metadata
-   * Creates a route definition compatible with @hono/zod-openapi.
-   *
-   * Scoped middleware and guards are NOT attached to `route.middleware`
-   * here — they're composed into a wrapped handler in `collectRoutes` so
-   * they run after Hono's request validators. See `wrapHandlerWithChain`.
+   * 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.
+   */
+  private resolveBody;
+  /**
+   * 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.
    */
-  private buildOpenAPIRoute;
+  private buildRouteMetadata;
   /**
    * Check if a body definition is a RouteBodyObject (has schema key) vs bare ZodType
    */
@@ -1326,6 +2125,140 @@ declare class RouteRegistrationService {
    * This ensures each request gets a fresh controller with request-scoped context
    */
   private createControllerHandler;
+  /**
+   * 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.
+   */
+  private applyCacheDecision;
+  /**
+   * 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.
+   */
+  private partitionsResolved;
+  /**
+   * `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.
+   */
+  private cachingAvailable;
+  /**
+   * 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.
+   */
+  private isGatewayRequest;
+  private executionCache;
+  /**
+   * 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.)
+   */
+  private buildTagScopes;
+  /**
+   * 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.
+   */
+  private partitionValues;
   /**
    * Extract the Zod schema from a RouteResponse definition.
    * Returns null for non-JSON content types or when no response is defined.
@@ -1393,6 +2326,13 @@ declare const ROUTER_TOKENS: {
    * URL generation service — route URLs, signed URLs, current/previous URL access
    */
   readonly Uri: symbol;
+  /**
+   * Token for RouteMetadataRegistry (singleton)
+   * Holds per-route schema metadata collected at registration so the OpenAPI
+   * document can be generated lazily (on request) without coupling routing to
+   * `@hono/zod-openapi`.
+   */
+  readonly RouteMetadataRegistry: symbol;
 };
 //#endregion
 //#region src/router/route-url.d.ts
@@ -1588,16 +2528,16 @@ declare function createMiddlewareChain(classes: Constructor<Middleware>[]): Midd
  * This is the core controller decorator that handles:
  * - Transient scope registration (request-scoped)
  * - Route metadata storage
- * - Controller options (tags, security schemes, hideFromDocs)
+ * - Controller options (tags, security schemes, groups, hideFromDocs)
  *
  * @param route - Base route for this controller (e.g., '/api/v1/users')
- * @param options - Optional configuration (tags, security schemes, hideFromDocs)
+ * @param options - Optional configuration (tags, security schemes, groups, hideFromDocs)
  *
  * @example
  * ```typescript
  * import { Controller } from 'stratal/router'
  *
- * @Controller('/api/v1/users', { tags: ['Users'] })
+ * @Controller('/api/v1/users', { tags: ['Users'], groups: ['admin'] })
  * export class UsersController implements IController {
  *   // All routes accessible
  * }
@@ -1625,6 +2565,13 @@ declare function getControllerOptions(target: object): ControllerOptions | undef
  * @returns Version string, array, VERSION_NEUTRAL symbol, or undefined if not set
  */
 declare function getControllerVersion(target: object): ControllerOptions['version'];
+/**
+ * Get the visibility groups from controller class metadata
+ *
+ * @param target - Controller class or instance
+ * @returns The controller's `groups`, or undefined if none were declared
+ */
+declare function getControllerGroups(target: object): ControllerOptions['groups'];
 //#endregion
 //#region src/router/decorators/http-method.decorator.d.ts
 /**
@@ -1635,12 +2582,14 @@ declare function getControllerVersion(target: object): ControllerOptions['versio
  *
  * @example
  * ```typescript
- * @Controller('/api/v1/users')
+ * import { array, object, uuid } from 'zod/mini'
+ *
+ * @Controller('/users', { version: '1' })
  * class UsersController {
- *   @Get('/', { response: z.array(userSchema), summary: 'List users' })
+ *   @Get('/', { response: array(userSchema), summary: 'List users' })
  *   async list(ctx: RouterContext) { ... }
  *
- *   @Get('/:id', { params: z.object({ id: z.string().uuid() }), response: userSchema })
+ *   @Get('/:id', { params: object({ id: uuid() }), response: userSchema })
  *   async getUser(ctx: RouterContext) { ... }
  * }
  * ```
@@ -1737,7 +2686,7 @@ declare const All: (path: string, config?: RouteConfig) => (target: object, prop
  *
  *   @Route({
  *     query: paginationSchema,
- *     response: z.array(noteSchema) // 200 auto-derived from 'index' method
+ *     response: array(noteSchema) // 200 auto-derived from 'index' method
  *   })
  *   async index(ctx: RouterContext): Promise<Response> {
  *     // GET /api/v1/notes (auto-derived)
@@ -1747,7 +2696,7 @@ declare const All: (path: string, config?: RouteConfig) => (target: object, prop
  *   }
  *
  *   @Route({
- *     params: z.object({ id: z.string().uuid() }),
+ *     params: object({ id: uuid() }),
  *     response: {
  *       schema: noteSchema,
  *       description: 'Note details'
@@ -1787,119 +2736,103 @@ declare function getRouteDecoratedMethods(ControllerClass: new (...args: unknown
 /**
  * Common OpenAPI Schemas
  *
- * Reusable schema definitions for common API patterns:
- * - Error responses
- * - Pagination
- * - Common parameters
- */
-/**
- * Generic error response schema
- * Used for all error responses (4xx, 5xx)
- * Matches the ErrorResponse shape produced by ExceptionHandler
- */
-declare const errorResponseSchema: z.ZodObject<{
-  message: z.ZodString;
-  timestamp: z.ZodString;
-  stack: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-/**
- * Validation error response schema
- * Used for 400 Bad Request with validation failures
- * Matches the ErrorResponse shape produced by ExceptionHandler
- */
-declare const validationErrorResponseSchema: z.ZodObject<{
-  message: z.ZodString;
-  timestamp: z.ZodString;
-  stack: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-/**
- * Pagination query parameters schema
- * Used for list endpoints
- */
-declare const paginationQuerySchema: z.ZodObject<{
-  page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
-  limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
-}, z.core.$strip>;
-/**
- * Paginated response wrapper schema
- * Generic wrapper for paginated list responses
- */
-declare const paginatedResponseSchema: <T extends z.ZodType>(itemSchema: T) => z.ZodObject<{
-  data: z.ZodArray<T>;
-  pagination: z.ZodObject<{
-    page: z.ZodNumber;
-    limit: z.ZodNumber;
-    total: z.ZodNumber;
-    totalPages: z.ZodNumber;
-  }, z.core.$strip>;
-}, z.core.$strip>;
-/**
- * UUID parameter schema
- * Used for :id parameters in RESTful routes
- */
-declare const uuidParamSchema: z.ZodObject<{
-  id: z.ZodString;
-}, z.core.$strip>;
-/**
- * Success message response schema
- * Used for operations that don't return data (e.g., DELETE)
- */
-declare const successMessageSchema: z.ZodObject<{
-  message: z.ZodString;
-  data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strip>;
-/**
- * Common HTTP status error schemas
- * Pre-configured for standard error responses
- */
+ * Reusable schema definitions for common API patterns (error responses,
+ * pagination, common parameters). Consumed by the lazy OpenAPI generator —
+ * never imported on the routing hot path — so these never reach a running
+ * worker unless the OpenAPI document is actually requested.
+ *
+ * Metadata (descriptions, component ids) is attached via the shared registry
+ * helpers; the generator reads `id` to emit shared `components.schemas` entries
+ * and `description` for field docs.
+ */
+/**
+ * Generic error response schema. Matches the ErrorResponse shape produced by
+ * ExceptionHandler. Used for all error responses (4xx, 5xx).
+ */
+declare const errorResponseSchema: import("zod/mini").ZodMiniObject<{
+  message: import("zod/mini").ZodMiniString<string>;
+  timestamp: iso.ZodMiniISODateTime;
+  stack: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
+}, import("zod/v4/core").$strip>;
+/** Validation error response schema (400 Bad Request). Shares the ErrorResponse shape. */
+declare const validationErrorResponseSchema: import("zod/mini").ZodMiniObject<{
+  message: import("zod/mini").ZodMiniString<string>;
+  timestamp: iso.ZodMiniISODateTime;
+  stack: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
+}, import("zod/v4/core").$strip>;
+/** Pagination query parameters for list endpoints. */
+declare const paginationQuerySchema: import("zod/mini").ZodMiniObject<{
+  page: import("zod/mini").ZodMiniDefault<import("zod/mini").ZodMiniNumber<unknown>>;
+  limit: import("zod/mini").ZodMiniDefault<import("zod/mini").ZodMiniNumber<unknown>>;
+}, import("zod/v4/core").$strip>;
+/** Generic wrapper for paginated list responses. */
+declare const paginatedResponseSchema: <T extends ZodType>(itemSchema: T) => import("zod/mini").ZodMiniObject<{
+  data: import("zod/mini").ZodMiniArray<T>;
+  pagination: import("zod/mini").ZodMiniObject<{
+    page: import("zod/mini").ZodMiniNumber<number>;
+    limit: import("zod/mini").ZodMiniNumber<number>;
+    total: import("zod/mini").ZodMiniNumber<number>;
+    totalPages: import("zod/mini").ZodMiniNumber<number>;
+  }, import("zod/v4/core").$strip>;
+}, import("zod/v4/core").$strip>;
+/** UUID parameter schema for `:id` parameters in RESTful routes. */
+declare const uuidParamSchema: import("zod/mini").ZodMiniObject<{
+  id: import("zod/mini").ZodMiniUUID;
+}, import("zod/v4/core").$strip>;
+/** Success message response for operations that don't return data (e.g. DELETE). */
+declare const successMessageSchema: import("zod/mini").ZodMiniObject<{
+  message: import("zod/mini").ZodMiniString<string>;
+  data: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniRecord<import("zod/mini").ZodMiniString<string>, import("zod/mini").ZodMiniUnknown>>;
+}, import("zod/v4/core").$strip>;
+/** Pre-configured error response schemas keyed by standard HTTP status. */
 declare const commonErrorSchemas: {
   readonly 400: {
-    readonly schema: z.ZodObject<{
-      message: z.ZodString;
-      timestamp: z.ZodString;
-      stack: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
-    readonly description: "Validation error";
+    readonly schema: import("zod/mini").ZodMiniObject<{
+      message: import("zod/mini").ZodMiniString<string>;
+      timestamp: iso.ZodMiniISODateTime;
+      stack: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
+    }, import("zod/v4/core").$strip>;
+    readonly description: 'Validation error';
   };
   readonly 401: {
-    readonly schema: z.ZodObject<{
-      message: z.ZodString;
-      timestamp: z.ZodString;
-      stack: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
-    readonly description: "Unauthorized";
+    readonly schema: import("zod/mini").ZodMiniObject<{
+      message: import("zod/mini").ZodMiniString<string>;
+      timestamp: iso.ZodMiniISODateTime;
+      stack: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
+    }, import("zod/v4/core").$strip>;
+    readonly description: 'Unauthorized';
   };
   readonly 403: {
-    readonly schema: z.ZodObject<{
-      message: z.ZodString;
-      timestamp: z.ZodString;
-      stack: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
-    readonly description: "Forbidden";
+    readonly schema: import("zod/mini").ZodMiniObject<{
+      message: import("zod/mini").ZodMiniString<string>;
+      timestamp: iso.ZodMiniISODateTime;
+      stack: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
+    }, import("zod/v4/core").$strip>;
+    readonly description: 'Forbidden';
   };
   readonly 404: {
-    readonly schema: z.ZodObject<{
-      message: z.ZodString;
-      timestamp: z.ZodString;
-      stack: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
-    readonly description: "Not found";
+    readonly schema: import("zod/mini").ZodMiniObject<{
+      message: import("zod/mini").ZodMiniString<string>;
+      timestamp: iso.ZodMiniISODateTime;
+      stack: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
+    }, import("zod/v4/core").$strip>;
+    readonly description: 'Not found';
   };
   readonly 409: {
-    readonly schema: z.ZodObject<{
-      message: z.ZodString;
-      timestamp: z.ZodString;
-      stack: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
-    readonly description: "Conflict";
+    readonly schema: import("zod/mini").ZodMiniObject<{
+      message: import("zod/mini").ZodMiniString<string>;
+      timestamp: iso.ZodMiniISODateTime;
+      stack: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
+    }, import("zod/v4/core").$strip>;
+    readonly description: 'Conflict';
   };
   readonly 500: {
-    readonly schema: z.ZodObject<{
-      message: z.ZodString;
-      timestamp: z.ZodString;
-      stack: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
-    readonly description: "Internal server error";
+    readonly schema: import("zod/mini").ZodMiniObject<{
+      message: import("zod/mini").ZodMiniString<string>;
+      timestamp: iso.ZodMiniISODateTime;
+      stack: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
+    }, import("zod/v4/core").$strip>;
+    readonly description: 'Internal server error';
   };
 };
 //#endregion
@@ -1941,6 +2874,16 @@ declare function parseDomainPattern(pattern: string): {
  */
 declare function createDomainMiddleware(pattern: string): MiddlewareHandler<RouterEnv>;
 //#endregion
+//#region src/router/nested-dispatch.d.ts
+/**
+ * Mark a request as dispatched into this app from inside another request.
+ *
+ * Returns the same object it was given, so it can be used inline.
+ */
+declare function markNestedDispatch(request: Request): Request;
+/** Whether this request was marked by {@link markNestedDispatch}. */
+declare function isNestedDispatch(request: Request): boolean;
+//#endregion
 //#region src/router/middleware/verify-signature.middleware.d.ts
 /**
  * Middleware that verifies signed URLs.
@@ -1963,7 +2906,7 @@ declare function createDomainMiddleware(pattern: string): MiddlewareHandler<Rout
  * ```
  */
 declare class VerifySignatureMiddleware implements Middleware {
-  handle(ctx: RouterContext, next: Next$1): Promise<void>;
+  handle(ctx: RouterContext, next: Next): Promise<void>;
 }
 //#endregion
 //#region src/router/signed-url.d.ts
@@ -2020,7 +2963,8 @@ declare class SchemaValidationError extends HttpException {
     message: string;
     code: string;
   }[];
-  constructor(zodError: ZodError);
+  constructor(zodError: $ZodError);
+  reportContext(): Record<string, unknown>;
 }
 //#endregion
 //#region src/router/errors/index.d.ts
@@ -2045,7 +2989,7 @@ declare class ResponseValidationError extends HttpException {
     message: string;
     code: string;
   }[];
-  constructor(zodError: ZodError);
+  constructor(zodError: $ZodError);
 }
 //#endregion
 //#region src/application.d.ts
@@ -2078,13 +3022,19 @@ declare class Application {
   private cronInitPromise;
   readonly env: StratalEnv;
   private readonly appConfig;
-  constructor({
-    env,
-    ctx,
-    ...config
-  }: ApplicationOptions);
+  constructor({ env, ctx, ...config }: ApplicationOptions);
   get container(): Container;
+  /** The application's logger (the singleton {@link LoggerService}). */
+  get logger(): LoggerService;
   ensureHono(): Promise<HonoApp>;
+  /**
+   * Whether the app registers any HTTP controllers. Cheap (reads the already-
+   * populated registry; no routing built) and only meaningful after
+   * {@link initialize}. The worker entry uses it to decide whether to pre-warm
+   * the routing stack at boot — queue/scheduled-only apps return false and never
+   * build routes they won't serve.
+   */
+  hasHttpRoutes(): boolean;
   get config(): ApplicationConfig;
   initialize(): Promise<void>;
   private initializeInternal;
@@ -2355,7 +3305,10 @@ declare class RouterContext<T extends RouterEnv = RouterEnv> extends Macroable {
    */
   getContainer(): Container;
   /**
-   * Set locale for the current request
+   * Override the locale for the current request (e.g. force a specific locale
+   * for this response). Request-scoped only — it does not persist. Persistence
+   * is the detection layer's job: cookie-strategy paths auto-persist the
+   * `locale` cookie (scoped via the config's `cookieOptions`).
    *
    * @param locale - Locale code (e.g., 'en', 'fr')
    */
@@ -2719,7 +3672,7 @@ interface ClassMetadata {
   token?: InjectionToken;
 }
 declare const Singleton: <T>(token?: InjectionToken<T>) => <TFunction extends abstract new (...args: never[]) => unknown>(target: TFunction) => TFunction;
-declare const Request: <T>(token?: InjectionToken<T>) => <TFunction extends abstract new (...args: never[]) => unknown>(target: TFunction) => TFunction;
+declare const Request$1: <T>(token?: InjectionToken<T>) => <TFunction extends abstract new (...args: never[]) => unknown>(target: TFunction) => TFunction;
 declare const Transient: <T>(token?: InjectionToken<T>) => <TFunction extends abstract new (...args: never[]) => unknown>(target: TFunction) => TFunction;
 declare function getClassMetadata(target: object): ClassMetadata | undefined;
 //#endregion
@@ -3053,5 +4006,5 @@ declare class AuthError extends ApplicationError {
   constructor(message?: string, cause?: unknown);
 }
 //#endregion
-export { Container as $, lazy as $n, getPathSpecificityScore as $t, Environment as A, ParsedOption as An, SerializedRoute as Ar, errorResponseSchema as At, getMetadata as B, ModuleOptions as Bn, Delete as Bt, ExceptionContext as C, Middleware as Cn, SECURITY_SCHEMES as Cr, SignedUrlOptions as Ct, createCronExceptionContext as D, CommandInternals as Dn, RouteName as Dr, createDomainMiddleware as Dt, createCliExceptionContext as E, CommandInput as En, RouteMatcher as Er, VerifySignatureMiddleware as Et, runWithContainer as F, DynamicModule as Fn, DI_TOKENS as Fr, validationErrorResponseSchema as Ft, getClassMetadata as G, ValueProvider as Gn, Controller as Gt, Request as H, OnInitialize as Hn, Patch as Ht, Disposable as I, ExistingProvider as In, ApplicationError as Ir, Route as It, INJECT_PARAM_METADATA_KEY as J, InjectionToken as Jn, getControllerVersion as Jt, getInjectionTokens as K, ContainerLike as Kn, getControllerOptions as Kt, disposeInstance as L, FactoryProvider as Ln, getRouteDecoratedMethods as Lt, isErrorResponse as M, Quarry as Mn, StratalRouteMap as Mr, paginationQuerySchema as Mt, containerStorage as N, AsyncModuleOptions as Nn, CONTAINER_TOKEN as Nr, successMessageSchema as Nt, createHttpExceptionContext as O, CommandResult as On, RouteParams as Or, parseDomainPattern as Ot, getContainer as P, ClassProvider as Pn, DIToken as Pr, uuidParamSchema as Pt, ContainerError as Q, isLazyToken as Qn, generateConventionRouteName as Qt, isDisposable as R, ModuleClass as Rn, getRouteMetadata as Rt, CronExceptionContext as S, HonoApp as Sn, ROUTE_METADATA_KEYS as Sr, RouterError as St, QueueExceptionContext as T, IController as Tn, CurrentRoute as Tr, verifySignedUrl as Tt, Singleton as U, OnShutdown as Un, Post as Ut, hasMetadata as V, OnException as Vn, Get as Vt, Transient as W, Provider as Wn, Put as Wt, ParamInjection as X, WhenOptions as Xn, extractDomainParamNames as Xt, InjectParam as Y, Scope as Yn, createMiddlewareChain as Yt, getMethodInjections as Z, LazyToken as Zn, extractParamNames as Zt, RenderableCallback as _, Router as _n, TrailingSlashMode as _r, StreamingApi$1 as _t, ContainerNotInitializedError as a, applyLocalePrefix as an, LocaleUrlConfig as ar, PredicateContainer as at, RespondCallback as b, LocalePathService as bn, HTTP_METHODS as br, SchemaValidationError as bt, HTTP_STATUS_MESSAGES as c, route as cn, RouteConfig as cr, SignedUriOptions as ct, DefaultExceptionHandler as d, RegisteredRoute as dn, RouteResponseObject as dr, buildRouteUrl as dt, sortRoutesBySpecificity as en, StratalExecutionContext as er, ContainerOptions as et, ExceptionHandler as f, RouteRegistrationInput as fn, RouterEnv as fr, Application as ft, LogSeverity as g, RouteConfigurable as gn, TrailingSlashExclude as gr, SSEStreamingApi$1 as gt, ErrorPageCallback as h, ModuleRegistry as hn, TrailingSlashConfig as hr, SSEMessage as ht, StratalNotInitializedError as i, resolveTrailingSlash as in, LocalePathConfig as ir, ConditionalBindingUse as it, ErrorResponse as j, ParsedSignature as jn, SerializedRoutes as jr, paginatedResponseSchema as jt, createQueueExceptionContext as k, ParsedArgument as kn, RoutePrefixes as kr, commonErrorSchemas as kt, HttpException as l, ROUTER_TOKENS as ln, RouteMetadata as lr, Uri as lt, ContextCallback as m, VersioningService as mn, SecurityScheme as mr, ApplicationOptions as mt, DatabaseError as n, applyTrailingSlash as nn, ConventionRouteMetadata as nr, ConditionalBindingBuilderImpl as nt, isApplicationError as o, shouldPrefixLocale as on, RouteBody as or, ContextQueryResult as ot, ApplicationErrorConstructor as p, RouteRegistry as pn, RouterVariables as pr, ApplicationConfig as pt, inject as q, ExtensionDecorator as qn, getControllerRoute as qt, StratalSupersededError as r, isTrailingSlashExcluded as rn, ExplicitRouteMetadata as rr, ConditionalBindingGive as rt, InternalError as s, stripLocalePrefix as sn, RouteBodyObject as sr, RouterContext as st, AuthError as t, toOpenAPIPath as tn, ControllerOptions as tr, ConditionalBindingBuilder as tt, abort as u, RouteRegistrationService as un, RouteResponse as ur, UriOptions as ut, Reportable as v, RouterGroupConfig as vn, TrailingSlashOptions as vr, InvalidSignatureError as vt, HttpExceptionContext as w, Next$1 as wn, VERSION_NEUTRAL as wr, signUrl as wt, CliExceptionContext as x, ResolvedPath as xn, ROUTER_CONTEXT_KEYS as xr, RouteNotFoundError as xt, ReportableCallback as y, LocaleUrlService as yn, VersioningOptions as yr, ResponseValidationError as yt, defineMetadata as z, ModuleContext as zn, All as zt };
-//# sourceMappingURL=index-uybm0bhQ.d.mts.map
+export { Container as $, ModuleClass as $n, RouteMatcher as $r, extractDomainParamNames as $t, Environment as A, DetectionStrategy as An, RouterVariables as Ar, parseDomainPattern as At, getMetadata as B, IController as Bn, SECURITY_SCHEMES as Br, getRouteMetadata as Bt, ExceptionContext as C, Router as Cn, RouteBody as Cr, SignedUrlOptions as Ct, createCronExceptionContext as D, ResolvedPath as Dn, RouteResponse as Dr, isNestedDispatch as Dt, createCliExceptionContext as E, LocalePathService as En, RouteMetadata as Er, VerifySignatureMiddleware as Et, runWithContainer as F, ResolvedI18nOptions as Fn, TrailingSlashOptions as Fr, successMessageSchema as Ft, getClassMetadata as G, ParsedOption as Gn, PartitionResolver as Gr, Post as Gt, Request$1 as H, CommandInternals as Hn, CacheableOptions as Hr, Delete as Ht, Disposable as I, buildDetectorOptions as In, VersioningOptions as Ir, uuidParamSchema as It, INJECT_PARAM_METADATA_KEY as J, AsyncModuleOptions as Jn, ResponseCacheGatewayOptions as Jr, getControllerGroups as Jt, getInjectionTokens as K, ParsedSignature as Kn, PurgesCacheOptions as Kr, Put as Kt, disposeInstance as L, resolveDetectionForPath as Ln, HTTP_METHODS as Lr, validationErrorResponseSchema as Lt, isErrorResponse as M, LOCALE_COOKIE as Mn, TrailingSlashConfig as Mr, errorResponseSchema as Mt, containerStorage as N, LanguageDetectionOptions as Nn, TrailingSlashExclude as Nr, paginatedResponseSchema as Nt, createHttpExceptionContext as O, DetectionConfig as On, RouteResponseObject as Or, markNestedDispatch as Ot, getContainer as P, ResolvedDetection as Pn, TrailingSlashMode as Pr, paginationQuerySchema as Pt, ContainerError as Q, FactoryProvider as Qn, CurrentRoute as Qr, createMiddlewareChain as Qt, isDisposable as R, resolveI18nOptions as Rn, ROUTER_CONTEXT_KEYS as Rr, Route as Rt, CronExceptionContext as S, RouteConfigurable as Sn, LocaleUrlConfig as Sr, RouterError as St, QueueExceptionContext as T, LocaleUrlService as Tn, RouteConfig as Tr, verifySignedUrl as Tt, Singleton as U, CommandResult as Un, CachedEntrypointName as Ur, Get as Ut, hasMetadata as V, CommandInput as Vn, VERSION_NEUTRAL as Vr, All as Vt, Transient as W, ParsedArgument as Wn, EntrypointNameFrom as Wr, Patch as Wt, ParamInjection as X, DynamicModule as Xn, Middleware as Xr, getControllerRoute as Xt, InjectParam as Y, ClassProvider as Yn, ResponseCacheModuleOptions as Yr, getControllerOptions as Yt, getMethodInjections as Z, ExistingProvider as Zn, Next as Zr, getControllerVersion as Zt, RenderableCallback as _, RouteRegistry as _n, WorkersCache as _r, StreamingApi$1 as _t, ContainerNotInitializedError as a, StratalRouteMap as ai, applyTrailingSlash as an, Provider as ar, PredicateContainer as at, RespondCallback as b, GatewayRouteTable as bn, ExplicitRouteMetadata as br, SchemaValidationError as bt, HTTP_STATUS_MESSAGES as c, DI_TOKENS as ci, applyLocalePrefix as cn, ExtensionDecorator as cr, SignedUriOptions as ct, DefaultExceptionHandler as d, route as dn, WhenOptions as dr, buildRouteUrl as dt, RouteName as ei, extractParamNames as en, ModuleContext as er, ContainerOptions as et, ExceptionHandler as f, ROUTER_TOKENS as fn, LazyToken as fr, Application as ft, LogSeverity as g, RouteRegistrationInput as gn, StratalExecutionContext as gr, SSEStreamingApi$1 as gt, ErrorPageCallback as h, RegisteredRoute as hn, PurgeSpec as hr, SSEMessage as ht, StratalNotInitializedError as i, SerializedRoutes as ii, toOpenAPIPath as in, OnShutdown as ir, ConditionalBindingUse as it, ErrorResponse as j, I18nModuleOptions as jn, SecurityScheme as jr, commonErrorSchemas as jt, createQueueExceptionContext as k, DetectionResolver as kn, RouterEnv as kr, createDomainMiddleware as kt, HttpException as l, ApplicationError as li, shouldPrefixLocale as ln, InjectionToken as lr, Uri as lt, ContextCallback as m, RouteSchemaMeta as mn, lazy as mr, ApplicationOptions as mt, DatabaseError as n, RoutePrefixes as ni, getPathSpecificityScore as nn, OnException as nr, ConditionalBindingBuilderImpl as nt, isApplicationError as o, CONTAINER_TOKEN as oi, isTrailingSlashExcluded as on, ValueProvider as or, ContextQueryResult as ot, ApplicationErrorConstructor as p, RouteRegistrationService as pn, isLazyToken as pr, ApplicationConfig as pt, inject as q, Quarry as qn, ResolvedCacheable as qr, Controller as qt, StratalSupersededError as r, SerializedRoute as ri, sortRoutesBySpecificity as rn, OnInitialize as rr, ConditionalBindingGive as rt, InternalError as s, DIToken as si, resolveTrailingSlash as sn, ContainerLike as sr, RouterContext as st, AuthError as t, RouteParams as ti, generateConventionRouteName as tn, ModuleOptions as tr, ConditionalBindingBuilder as tt, abort as u, stripLocalePrefix as un, Scope as ur, UriOptions as ut, Reportable as v, VersioningService as vn, ControllerOptions as vr, InvalidSignatureError as vt, HttpExceptionContext as w, RouterGroupConfig as wn, RouteBodyObject as wr, signUrl as wt, CliExceptionContext as x, ModuleRegistry as xn, LocalePathConfig as xr, RouteNotFoundError as xt, ReportableCallback as y, GatewayRouteEntry as yn, ConventionRouteMetadata as yr, ResponseValidationError as yt, defineMetadata as z, HonoApp as zn, ROUTE_METADATA_KEYS as zr, getRouteDecoratedMethods as zt };
+//# sourceMappingURL=index-B2WtEagR.d.mts.map