@voyant-travel/hono 0.110.3 → 0.112.0

package/dist/app.d.ts

@@ -36,7 +36,14 @@ export interface VoyantAppExtensions<TBindings = unknown> {
      */
     eventBus: import("@voyant-travel/core").EventBus;
 }
-export declare function createApp<TBindings extends VoyantBindings>(config: VoyantAppConfig<TBindings>): Hono<{
+/**
+ * Low-level app factory: given an already-resolved `modules`/`extensions` set
+ * (plus middleware config), build the Hono app. Most deployments use the
+ * config-driven `createApp` (see `create-app.ts`), which derives the modules
+ * from a manifest + registry + capabilities and delegates here. Use `mountApp`
+ * directly only when you have the resolved set in hand (tests, advanced hosts).
+ */
+export declare function mountApp<TBindings extends VoyantBindings>(config: VoyantAppConfig<TBindings>): Hono<{
     Bindings: TBindings;
     Variables: VoyantVariables;
 }> & VoyantAppExtensions<TBindings>;

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AA4B3B,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAY,eAAe,EAAE,MAAM,YAAY,CAAA;AA2C5F;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB,CAAC,SAAS,GAAG,OAAO;IACtD;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1C;;;;;;;;OAQG;IACH,QAAQ,EAAE,OAAO,qBAAqB,EAAE,QAAQ,CAAA;CACjD;AAED,wBAAgB,SAAS,CAAC,SAAS,SAAS,cAAc,EACxD,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,GACjC,IAAI,CAAC;IAAE,QAAQ,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,eAAe,CAAA;CAAE,CAAC,GAAG,mBAAmB,CAAC,SAAS,CAAC,CA6Z5F"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AA6B3B,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAY,eAAe,EAAE,MAAM,YAAY,CAAA;AA2C5F;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB,CAAC,SAAS,GAAG,OAAO;IACtD;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1C;;;;;;;;OAQG;IACH,QAAQ,EAAE,OAAO,qBAAqB,EAAE,QAAQ,CAAA;CACjD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,SAAS,SAAS,cAAc,EACvD,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,GACjC,IAAI,CAAC;IAAE,QAAQ,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,eAAe,CAAA;CAAE,CAAC,GAAG,mBAAmB,CAAC,SAAS,CAAC,CA6a5F"}

package/dist/app.js

@@ -2,6 +2,7 @@ import { createContainer, createEventBus, createQueryRunner, } from "@voyant-tra
 import { createOutboxEventStore } from "@voyant-travel/db/outbox";
 import { Hono } from "hono";
 import { containerToServiceResolver, makeFrameworkLogger, wireWorkflowRuntime, } from "./app-workflows.js";
+import { mountLazyRoutePaths, mountLazyRoutesAt } from "./lazy-routes.js";
 import { createPathDbSelector } from "./lib/db-selector.js";
 import { tryGetExecutionCtx } from "./lib/execution-ctx.js";
 import { matchesPublicPath, normalizePathname } from "./lib/public-paths.js";
@@ -41,7 +42,14 @@ function buildRateLimitPolicy(config, env, bucket, defaults) {
         store: resolveConfiguredRateLimitStore(config, env) ?? resolveRateLimitStore({ env }),
     };
 }
-export function createApp(config) {
+/**
+ * Low-level app factory: given an already-resolved `modules`/`extensions` set
+ * (plus middleware config), build the Hono app. Most deployments use the
+ * config-driven `createApp` (see `create-app.ts`), which derives the modules
+ * from a manifest + registry + capabilities and delegates here. Use `mountApp`
+ * directly only when you have the resolved set in hand (tests, advanced hosts).
+ */
+export function mountApp(config) {
     const app = new Hono();
     app.onError(handleApiError);
     // Expand plugins into their constituent modules/extensions before mounting
@@ -358,11 +366,22 @@ export function createApp(config) {
     }
     // Mount module routes
     for (const mod of allModules) {
+        const adminPrefix = `/v1/admin/${mod.module.name}`;
+        const publicPrefix = resolveSurfaceMountPath("/v1/public", mod.publicPath, mod.module.name);
         if (mod.adminRoutes) {
-            app.route(`/v1/admin/${mod.module.name}`, mod.adminRoutes);
+            app.route(adminPrefix, mod.adminRoutes);
         }
         if (mod.publicRoutes) {
-            app.route(resolveSurfaceMountPath("/v1/public", mod.publicPath, mod.module.name), mod.publicRoutes);
+            app.route(publicPrefix, mod.publicRoutes);
+        }
+        if (mod.lazyAdminRoutes) {
+            mountLazyRoutesAt(app, adminPrefix, mod.lazyAdminRoutes);
+        }
+        if (mod.lazyPublicRoutes) {
+            mountLazyRoutesAt(app, publicPrefix, mod.lazyPublicRoutes);
+        }
+        if (mod.lazyRoutes) {
+            mountLazyRoutePaths(app, mod.lazyRoutes.paths, mod.lazyRoutes.load);
         }
         if (mod.routes) {
             app.route(`/v1/${mod.module.name}`, mod.routes);
@@ -370,11 +389,22 @@ export function createApp(config) {
     }
     // Mount extension routes
     for (const ext of allExtensions) {
+        const adminPrefix = `/v1/admin/${ext.extension.module}`;
+        const publicPrefix = resolveSurfaceMountPath("/v1/public", ext.publicPath, ext.extension.module);
         if (ext.adminRoutes) {
-            app.route(`/v1/admin/${ext.extension.module}`, ext.adminRoutes);
+            app.route(adminPrefix, ext.adminRoutes);
         }
         if (ext.publicRoutes) {
-            app.route(resolveSurfaceMountPath("/v1/public", ext.publicPath, ext.extension.module), ext.publicRoutes);
+            app.route(publicPrefix, ext.publicRoutes);
+        }
+        if (ext.lazyAdminRoutes) {
+            mountLazyRoutesAt(app, adminPrefix, ext.lazyAdminRoutes);
+        }
+        if (ext.lazyPublicRoutes) {
+            mountLazyRoutesAt(app, publicPrefix, ext.lazyPublicRoutes);
+        }
+        if (ext.lazyRoutes) {
+            mountLazyRoutePaths(app, ext.lazyRoutes.paths, ext.lazyRoutes.load);
         }
         if (ext.routes) {
             app.route(`/v1/${ext.extension.module}`, ext.routes);

package/dist/create-app.d.ts

@@ -0,0 +1,36 @@
+import { type CompositionManifest, type CompositionRegistry } from "./composition.js";
+import type { VoyantAppConfig, VoyantBindings } from "./types.js";
+/**
+ * Config-driven app config: the manifest + registry + capabilities replace the
+ * resolved `modules`/`extensions` of {@link VoyantAppConfig}. Everything else
+ * (db surfaces, auth, plugins, publicPaths, …) is unchanged.
+ */
+export interface CreateAppConfig<TBindings extends VoyantBindings, TCapabilities> extends Omit<VoyantAppConfig<TBindings>, "modules" | "extensions"> {
+    /** Ordered module/extension manifest. */
+    manifest: CompositionManifest;
+    /** Maps each manifest entry to its factory. */
+    registry: CompositionRegistry<TCapabilities>;
+    /** Deployment capabilities passed to every registry factory. */
+    capabilities: TCapabilities;
+}
+/**
+ * The low-level config-driven front door. Derives the module/extension set from
+ * an explicit manifest + registry + capabilities, then mounts the app — instead
+ * of `composeFromManifest(...)` followed by `mountApp(...)`:
+ *
+ *     export const app = createApp<CloudflareBindings, Providers>({
+ *       manifest: runtimeManifest,
+ *       registry: composition,
+ *       capabilities: buildProviders(),
+ *       db, auth, plugins, ...
+ *     })
+ *
+ * Standard deployments usually call `@voyant-travel/framework`'s higher-level
+ * `createVoyantApp({ providers, modules })` (which assembles the framework-owned
+ * manifest + registry for you and delegates here) rather than this directly.
+ */
+export declare function createApp<TBindings extends VoyantBindings, TCapabilities>(config: CreateAppConfig<TBindings, TCapabilities>): import("hono").Hono<{
+    Bindings: TBindings;
+    Variables: import("./types.js").VoyantVariables;
+}, import("hono/types").BlankSchema, "/"> & import("./app.js").VoyantAppExtensions<TBindings>;
+//# sourceMappingURL=create-app.d.ts.map

package/dist/create-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-app.d.ts","sourceRoot":"","sources":["../src/create-app.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EAEzB,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEjE;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,SAAS,SAAS,cAAc,EAAE,aAAa,CAC9E,SAAQ,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,YAAY,CAAC;IAClE,yCAAyC;IACzC,QAAQ,EAAE,mBAAmB,CAAA;IAC7B,+CAA+C;IAC/C,QAAQ,EAAE,mBAAmB,CAAC,aAAa,CAAC,CAAA;IAC5C,gEAAgE;IAChE,YAAY,EAAE,aAAa,CAAA;CAC5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,SAAS,SAAS,cAAc,EAAE,aAAa,EACvE,MAAM,EAAE,eAAe,CAAC,SAAS,EAAE,aAAa,CAAC;;;8FAKlD"}

package/dist/create-app.js

@@ -0,0 +1,23 @@
+import { mountApp } from "./app.js";
+import { composeFromManifest, } from "./composition.js";
+/**
+ * The low-level config-driven front door. Derives the module/extension set from
+ * an explicit manifest + registry + capabilities, then mounts the app — instead
+ * of `composeFromManifest(...)` followed by `mountApp(...)`:
+ *
+ *     export const app = createApp<CloudflareBindings, Providers>({
+ *       manifest: runtimeManifest,
+ *       registry: composition,
+ *       capabilities: buildProviders(),
+ *       db, auth, plugins, ...
+ *     })
+ *
+ * Standard deployments usually call `@voyant-travel/framework`'s higher-level
+ * `createVoyantApp({ providers, modules })` (which assembles the framework-owned
+ * manifest + registry for you and delegates here) rather than this directly.
+ */
+export function createApp(config) {
+    const { manifest, registry, capabilities, ...rest } = config;
+    const { modules, extensions } = composeFromManifest(manifest, registry, capabilities);
+    return mountApp({ ...rest, modules, extensions });
+}

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 export type { VoyantPermission } from "@voyant-travel/core";
-export { createApp } from "./app.js";
+export { mountApp } from "./app.js";
 export type { SessionAuthContext } from "./auth/index.js";
 export { constantTimeEqual, extractBearerToken, generateNumericCode, randomBytesHex, requireUserId, sha256Base64Url, sha256Hex, unsignCookie, verifySession, } from "./auth/index.js";
+export { type CreateAppConfig, createApp } from "./create-app.js";
 export type { DocumentDownloadEnvelope, DocumentDownloadResolution, DocumentDownloadResolver, DocumentDownloadResolverResult, StoredDocumentReference, } from "./document-download.js";
 export { resolveStoredDocumentDownload } from "./document-download.js";
+export { createLazyRouteHandler, type LazyHonoRoutes, type LazyRoutesLoader, mountLazyRoutePaths, mountLazyRoutesAt, } from "./lazy-routes.js";
 export { createPathDbSelector, type PathDbSelectorOptions } from "./lib/db-selector.js";
 export { clientIpKey, consoleLoggerProvider, cors, DEFAULT_IDEMPOTENCY_TTL_MS, db, enforceRateLimit, errorBoundary, handleApiError, type IdempotencyKeyOptions, idempotencyKey, LIVE_LIMITS, logger, purgeExpiredIdempotencyKeys, rateLimit, requestId, requireActor, requireAuth, requirePermission, } from "./middleware/index.js";
 export type { HonoExtension, HonoModule } from "./module.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACpC,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,aAAa,EACb,eAAe,EACf,SAAS,EACT,YAAY,EACZ,aAAa,GACd,MAAM,iBAAiB,CAAA;AACxB,YAAY,EACV,wBAAwB,EACxB,0BAA0B,EAC1B,wBAAwB,EACxB,8BAA8B,EAC9B,uBAAuB,GACxB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,6BAA6B,EAAE,MAAM,wBAAwB,CAAA;AACtE,OAAO,EAAE,oBAAoB,EAAE,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AACvF,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,IAAI,EACJ,0BAA0B,EAC1B,EAAE,EACF,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,KAAK,qBAAqB,EAC1B,cAAc,EACd,WAAW,EACX,MAAM,EACN,2BAA2B,EAC3B,SAAS,EACT,SAAS,EACT,YAAY,EACZ,WAAW,EACX,iBAAiB,GAClB,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC5D,YAAY,EACV,mBAAmB,EACnB,mBAAmB,EACnB,UAAU,EACV,UAAU,GACX,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,aAAa,CAAA;AACpB,YAAY,EACV,6BAA6B,EAC7B,6BAA6B,EAC7B,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC5B,+BAA+B,EAC/B,2BAA2B,GAC5B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,KAAK,iCAAiC,EACtC,6CAA6C,EAC7C,iCAAiC,EACjC,sCAAsC,EACtC,kCAAkC,EAClC,KAAK,mCAAmC,EACxC,KAAK,8BAA8B,EACnC,KAAK,2BAA2B,EAChC,KAAK,gCAAgC,EACrC,KAAK,gCAAgC,EACrC,KAAK,kCAAkC,EACvC,KAAK,4BAA4B,EACjC,KAAK,sCAAsC,EAC3C,kCAAkC,EAClC,iCAAiC,GAClC,MAAM,+BAA+B,CAAA;AACtC,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,kBAAkB,EAClB,QAAQ,EACR,cAAc,EACd,eAAe,EACf,qBAAqB,EACrB,wBAAwB,EACxB,qBAAqB,EACrB,cAAc,EACd,QAAQ,EACR,sBAAsB,EACtB,kBAAkB,EAClB,wBAAwB,EACxB,eAAe,GAChB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,wBAAwB,EACxB,aAAa,EACb,qBAAqB,EACrB,UAAU,EACV,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACnC,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,aAAa,EACb,eAAe,EACf,SAAS,EACT,YAAY,EACZ,aAAa,GACd,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,KAAK,eAAe,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AACjE,YAAY,EACV,wBAAwB,EACxB,0BAA0B,EAC1B,wBAAwB,EACxB,8BAA8B,EAC9B,uBAAuB,GACxB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,6BAA6B,EAAE,MAAM,wBAAwB,CAAA;AACtE,OAAO,EACL,sBAAsB,EACtB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,oBAAoB,EAAE,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AACvF,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,IAAI,EACJ,0BAA0B,EAC1B,EAAE,EACF,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,KAAK,qBAAqB,EAC1B,cAAc,EACd,WAAW,EACX,MAAM,EACN,2BAA2B,EAC3B,SAAS,EACT,SAAS,EACT,YAAY,EACZ,WAAW,EACX,iBAAiB,GAClB,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC5D,YAAY,EACV,mBAAmB,EACnB,mBAAmB,EACnB,UAAU,EACV,UAAU,GACX,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,aAAa,CAAA;AACpB,YAAY,EACV,6BAA6B,EAC7B,6BAA6B,EAC7B,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC5B,+BAA+B,EAC/B,2BAA2B,GAC5B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,KAAK,iCAAiC,EACtC,6CAA6C,EAC7C,iCAAiC,EACjC,sCAAsC,EACtC,kCAAkC,EAClC,KAAK,mCAAmC,EACxC,KAAK,8BAA8B,EACnC,KAAK,2BAA2B,EAChC,KAAK,gCAAgC,EACrC,KAAK,gCAAgC,EACrC,KAAK,kCAAkC,EACvC,KAAK,4BAA4B,EACjC,KAAK,sCAAsC,EAC3C,kCAAkC,EAClC,iCAAiC,GAClC,MAAM,+BAA+B,CAAA;AACtC,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,kBAAkB,EAClB,QAAQ,EACR,cAAc,EACd,eAAe,EACf,qBAAqB,EACrB,wBAAwB,EACxB,qBAAqB,EACrB,cAAc,EACd,QAAQ,EACR,sBAAsB,EACtB,kBAAkB,EAClB,wBAAwB,EACxB,eAAe,GAChB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,wBAAwB,EACxB,aAAa,EACb,qBAAqB,EACrB,UAAU,EACV,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -1,6 +1,8 @@
-export { createApp } from "./app.js";
+export { mountApp } from "./app.js";
 export { constantTimeEqual, extractBearerToken, generateNumericCode, randomBytesHex, requireUserId, sha256Base64Url, sha256Hex, unsignCookie, verifySession, } from "./auth/index.js";
+export { createApp } from "./create-app.js";
 export { resolveStoredDocumentDownload } from "./document-download.js";
+export { createLazyRouteHandler, mountLazyRoutePaths, mountLazyRoutesAt, } from "./lazy-routes.js";
 export { createPathDbSelector } from "./lib/db-selector.js";
 export { clientIpKey, consoleLoggerProvider, cors, DEFAULT_IDEMPOTENCY_TTL_MS, db, enforceRateLimit, errorBoundary, handleApiError, idempotencyKey, LIVE_LIMITS, logger, purgeExpiredIdempotencyKeys, rateLimit, requestId, requireActor, requireAuth, requirePermission, } from "./middleware/index.js";
 export { defineHonoBundle, defineHonoPlugin, expandHonoBundles, expandHonoPlugins, } from "./plugin.js";

package/dist/lazy-routes.d.ts

@@ -0,0 +1,67 @@
+/**
+ * First-class lazy route mounting for `@voyant-travel/hono`.
+ *
+ * A module or extension can declare `lazyAdminRoutes` / `lazyPublicRoutes` as a
+ * loader (`() => import("./routes").then((m) => m.createRoutes(opts))`) instead
+ * of eager `adminRoutes` / `publicRoutes`. The route bundle is dynamically
+ * imported on first matching request and cached per isolate/process, so heavy
+ * route families don't inflate the main bundle or the Worker cold start.
+ *
+ * For deployment-local families that span MULTIPLE absolute path prefixes (e.g.
+ * an operator bundle exposing `/v1/uploads`, `/v1/admin/uploads`, `/v1/media/*`),
+ * the single-surface loaders don't fit. Such families declare `lazyRoutes`:
+ * `{ paths, load }` where `load` returns a sub-app whose routes are ABSOLUTE and
+ * `paths` are the explicit matchers the framework installs up front. This is the
+ * context-preserving replacement for the starter's `mountLazyRouteApp(...)`.
+ *
+ * The hard requirement (and the reason the starter's old `mountLazyRouteApp`
+ * was insufficient): the lazy routes must behave **exactly** like eager routes.
+ * Eager routes mounted via `app.route(...)` share the request context, so they
+ * see `c.var.db`, `c.var.container`, the resolved actor, etc. set by the
+ * `createApp` middleware pipeline. A naive `subApp.fetch(c.req.raw, c.env)`
+ * forward builds a fresh context and drops every `c.var`.
+ *
+ * So this dispatcher bridges the request-scoped context across the forward: it
+ * snapshots `c.var`, carries it on the forwarded `env` under a private symbol,
+ * and a wrapper middleware re-hydrates it onto the loaded sub-app's context
+ * before the real routes run. The db lease is *carried*, not re-acquired — the
+ * outer `db` middleware still owns its lifecycle (dispose), so there is no
+ * double-release.
+ */
+import type { Context, Hono as HonoType } from "hono";
+type AnyHono = HonoType<any>;
+/** Loads (and builds) the Hono sub-app for a lazy route surface. */
+export type LazyRoutesLoader = () => Promise<AnyHono>;
+/**
+ * A deployment-local lazy route family spanning explicit absolute path
+ * matchers. `load` returns a sub-app whose routes are ABSOLUTE; `paths` are the
+ * matchers the framework installs up front (no bundle import until a request
+ * matches).
+ */
+export interface LazyHonoRoutes {
+    paths: readonly string[];
+    load: LazyRoutesLoader;
+}
+/**
+ * Build a cached, context-preserving request handler. `mountPrefix` is where the
+ * loaded routes are re-mounted in the wrapper sub-app so the forwarded absolute
+ * request URL matches: the surface prefix (e.g. `/v1/admin/flights`) for
+ * relative-route loaders, or `"/"` for loaders that already return absolute
+ * routes.
+ */
+export declare function createLazyRouteHandler(mountPrefix: string, load: LazyRoutesLoader): (c: Context) => Promise<Response>;
+/**
+ * Register a single lazy surface on `app` at `prefix` (loader returns RELATIVE
+ * routes). Matches both the prefix root (`POST /v1/admin/foo`) and any sub-path
+ * (`/v1/admin/foo/bar`).
+ */
+export declare function mountLazyRoutesAt(app: AnyHono, prefix: string, load: LazyRoutesLoader): void;
+/**
+ * Register a multi-prefix lazy family on `app` at explicit `paths` (loader
+ * returns ABSOLUTE routes). One shared cached/context-bridging handler backs
+ * every path. Context-preserving replacement for the starter's
+ * `mountLazyRouteApp(...)`.
+ */
+export declare function mountLazyRoutePaths(app: AnyHono, paths: readonly string[], load: LazyRoutesLoader): void;
+export {};
+//# sourceMappingURL=lazy-routes.d.ts.map

package/dist/lazy-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-routes.d.ts","sourceRoot":"","sources":["../src/lazy-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,MAAM,CAAA;AAMrD,KAAK,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAA;AAE5B,oEAAoE;AACpE,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;AAErD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB,IAAI,EAAE,gBAAgB,CAAA;CACvB;AAKD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,IA0ClE,GAAG,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAO7C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAI5F;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,IAAI,EAAE,gBAAgB,GACrB,IAAI,CAKN"}

package/dist/lazy-routes.js

@@ -0,0 +1,79 @@
+import { Hono } from "hono";
+import { tryGetExecutionCtx } from "./lib/execution-ctx.js";
+/** Private carrier key for snapshotting `c.var` across the forward. */
+const LAZY_CONTEXT_CARRIER = Symbol.for("voyant.hono.lazyContextCarrier");
+/**
+ * Build a cached, context-preserving request handler. `mountPrefix` is where the
+ * loaded routes are re-mounted in the wrapper sub-app so the forwarded absolute
+ * request URL matches: the surface prefix (e.g. `/v1/admin/flights`) for
+ * relative-route loaders, or `"/"` for loaders that already return absolute
+ * routes.
+ */
+export function createLazyRouteHandler(mountPrefix, load) {
+    let cached;
+    function getApp() {
+        // Cache the BUILT, wrapped sub-app; reset on failure so a transient
+        // import/config error can recover on the next request.
+        if (!cached) {
+            cached = load()
+                .then((routes) => {
+                const wrapped = new Hono();
+                // Re-throw handler errors instead of letting the wrapper sub-app's
+                // default Hono error handler swallow them into a plain 500. This
+                // propagates the throw back through `app.fetch` to the outer
+                // `createApp` pipeline, so lazy routes hit the same `errorBoundary` /
+                // `handleApiError` normalization (JSON error shape + structured
+                // logging) as eager `app.route(...)` mounts.
+                wrapped.onError((err) => {
+                    throw err;
+                });
+                wrapped.use("*", async (cc, next) => {
+                    const carried = cc.env?.[LAZY_CONTEXT_CARRIER];
+                    if (carried) {
+                        for (const [key, value] of Object.entries(carried)) {
+                            // biome-ignore lint/suspicious/noExplicitAny: re-hydrating arbitrary context vars -- owner: hono.
+                            cc.set(key, value);
+                        }
+                    }
+                    await next();
+                });
+                wrapped.route(mountPrefix, routes);
+                return wrapped;
+            })
+                .catch((err) => {
+                cached = undefined;
+                throw err;
+            });
+        }
+        return cached;
+    }
+    return async (c) => {
+        const app = await getApp();
+        const snapshot = { ...c.var };
+        const env = { ...c.env, [LAZY_CONTEXT_CARRIER]: snapshot };
+        // biome-ignore lint/suspicious/noExplicitAny: forward the host execution context when present -- owner: hono.
+        return app.fetch(c.req.raw, env, tryGetExecutionCtx(c));
+    };
+}
+/**
+ * Register a single lazy surface on `app` at `prefix` (loader returns RELATIVE
+ * routes). Matches both the prefix root (`POST /v1/admin/foo`) and any sub-path
+ * (`/v1/admin/foo/bar`).
+ */
+export function mountLazyRoutesAt(app, prefix, load) {
+    const handler = createLazyRouteHandler(prefix, load);
+    app.all(prefix, handler);
+    app.all(`${prefix}/*`, handler);
+}
+/**
+ * Register a multi-prefix lazy family on `app` at explicit `paths` (loader
+ * returns ABSOLUTE routes). One shared cached/context-bridging handler backs
+ * every path. Context-preserving replacement for the starter's
+ * `mountLazyRouteApp(...)`.
+ */
+export function mountLazyRoutePaths(app, paths, load) {
+    const handler = createLazyRouteHandler("/", load);
+    for (const path of paths) {
+        app.all(path, handler);
+    }
+}

package/dist/module.d.ts

@@ -1,5 +1,6 @@
 import type { Extension, Module } from "@voyant-travel/core";
 import type { Hono } from "hono";
+import type { LazyHonoRoutes, LazyRoutesLoader } from "./lazy-routes.js";
 export interface HonoModule {
     module: Module;
     /**
@@ -14,6 +15,22 @@ export interface HonoModule {
     adminRoutes?: Hono<any>;
     /** Customer/partner/supplier-facing routes — mounted at `/v1/public/{module.name}`. */
     publicRoutes?: Hono<any>;
+    /**
+     * Lazy variant of `adminRoutes` — the route bundle is dynamically imported on
+     * first request and cached per isolate. Mounted at `/v1/admin/{module.name}`
+     * with the request context bridged in, so it behaves identically to eager
+     * `adminRoutes`. Use for heavy route families to protect Worker cold start.
+     */
+    lazyAdminRoutes?: LazyRoutesLoader;
+    /** Lazy variant of `publicRoutes` — mounted at `/v1/public/{publicPath ?? module.name}`. */
+    lazyPublicRoutes?: LazyRoutesLoader;
+    /**
+     * Deployment-local lazy family spanning explicit absolute path matchers (for
+     * route bundles that don't fit a single admin/public surface). The loader
+     * returns ABSOLUTE routes; the framework mounts + caches them with the request
+     * context bridged in. Context-preserving replacement for `mountLazyRouteApp`.
+     */
+    lazyRoutes?: LazyHonoRoutes;
     /**
      * Optional override for the public mount path relative to `/v1/public`.
      *
@@ -30,6 +47,12 @@ export interface HonoExtension {
     adminRoutes?: Hono<any>;
     /** Customer/partner/supplier-facing routes — mounted at `/v1/public/{extension.module}`. */
     publicRoutes?: Hono<any>;
+    /** Lazy variant of `adminRoutes` — mounted at `/v1/admin/{extension.module}` (see HonoModule). */
+    lazyAdminRoutes?: LazyRoutesLoader;
+    /** Lazy variant of `publicRoutes` — mounted at `/v1/public/{publicPath ?? extension.module}`. */
+    lazyPublicRoutes?: LazyRoutesLoader;
+    /** Deployment-local lazy family at explicit absolute paths (see HonoModule). */
+    lazyRoutes?: LazyHonoRoutes;
     /**
      * Optional override for the public mount path relative to `/v1/public`.
      *

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAC5D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAEhC,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;OAMG;IAEH,MAAM,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;IAClB,kEAAkE;IAElE,WAAW,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;IACvB,uFAAuF;IAEvF,YAAY,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;IACxB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,SAAS,CAAA;IACpB,0DAA0D;IAE1D,MAAM,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;IAClB,uEAAuE;IAEvE,WAAW,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;IACvB,4FAA4F;IAE5F,YAAY,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;IACxB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAC5D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAEhC,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAExE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;OAMG;IAEH,MAAM,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;IAClB,kEAAkE;IAElE,WAAW,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;IACvB,uFAAuF;IAEvF,YAAY,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;IACxB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,gBAAgB,CAAA;IAClC,4FAA4F;IAC5F,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IACnC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,cAAc,CAAA;IAC3B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,SAAS,CAAA;IACpB,0DAA0D;IAE1D,MAAM,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;IAClB,uEAAuE;IAEvE,WAAW,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;IACvB,4FAA4F;IAE5F,YAAY,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;IACxB,kGAAkG;IAClG,eAAe,CAAC,EAAE,gBAAgB,CAAA;IAClC,iGAAiG;IACjG,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IACnC,gFAAgF;IAChF,UAAU,CAAC,EAAE,cAAc,CAAA;IAC3B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyant-travel/hono",
-  "version": "0.110.3",
+  "version": "0.112.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -119,19 +119,19 @@
     "drizzle-orm": "^0.45.2",
     "hono": "^4.12.10",
     "zod": "^4.3.6",
-    "@voyant-travel/core": "^0.109.0",
-    "@voyant-travel/db": "^0.108.1",
-    "@voyant-travel/storage": "^0.104.1",
+    "@voyant-travel/core": "^0.110.0",
+    "@voyant-travel/db": "^0.108.2",
+    "@voyant-travel/storage": "^0.105.0",
     "@voyant-travel/types": "^0.104.5",
     "@voyant-travel/utils": "^0.105.2",
-    "@voyant-travel/workflows": "^0.109.1"
+    "@voyant-travel/workflows": "^0.109.4"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260426.1",
     "typescript": "^6.0.2",
     "vitest": "^4.1.2",
     "@voyant-travel/voyant-typescript-config": "^0.1.0",
-    "@voyant-travel/workflows-orchestrator": "^0.109.1"
+    "@voyant-travel/workflows-orchestrator": "^0.109.4"
   },
   "files": [
     "dist"