@voyant-travel/hono 0.118.4 → 0.120.0

package/dist/app.d.ts

@@ -17,6 +17,20 @@ export interface LazyMount {
     prefix: string;
     load: LazyRoutesLoader;
 }
+/**
+ * A single module route mount recorded at mount time so a build-time generator
+ * can produce one self-contained OpenAPI document per module (voyant#2733).
+ * Mirrors `ModuleMount` in `./openapi.ts` (structurally identical, declared here
+ * to keep the build-time-only openapi module out of the runtime path). `load`
+ * returns the sub-app without serving it — eager mounts wrap the already-built
+ * routes as `() => routes`; lazy mounts pass their loader.
+ */
+export interface ModuleMount {
+    moduleName: string;
+    /** Absolute surface mount prefix, or `"/"` for absolute `lazyRoutes`. */
+    prefix: string;
+    load: () => Hono<any, any, any> | Promise<Hono<any, any, any>>;
+}
 /**
  * App handle returned alongside the Hono instance. Carries `ready()` for
  * headless / sibling-process deployments that need to fire the lazy
@@ -59,6 +73,14 @@ export interface VoyantAppExtensions<TBindings = unknown> {
      * `.openapi()` operations via `mergeLazyOpenApiPaths`. Never read at runtime.
      */
     lazyMounts: LazyMount[];
+    /**
+     * Every module route mount (admin + public, eager + lazy), tagged with its
+     * owning module name (voyant#2733). A build-time generator reads this to
+     * produce one self-contained OpenAPI document per module via
+     * `generateModuleOpenApiDocuments`, keeping the module boundary authoritative
+     * rather than guessed from path prefixes. Never read at runtime.
+     */
+    moduleMounts: ModuleMount[];
 }
 /**
  * Low-level app factory: given an already-resolved `modules`/`extensions` set

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAQhC,OAAO,EAAE,KAAK,gBAAgB,EAA0C,MAAM,kBAAkB,CAAA;AA+BhG,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAY,eAAe,EAAE,MAAM,YAAY,CAAA;AAI5F,4EAA4E;AAC5E,KAAK,QAAQ,CAAC,SAAS,SAAS,cAAc,IAAI;IAChD,QAAQ,EAAE,SAAS,CAAA;IACnB,SAAS,EAAE,eAAe,CAAA;CAC3B,CAAA;AAuBD;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,gBAAgB,CAAA;CACvB;AAED;;;;;;;;;;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;IAChD;;;;;OAKG;IACH,UAAU,EAAE,SAAS,EAAE,CAAA;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,SAAS,SAAS,cAAc,EACvD,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,GACjC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAue5D"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAQhC,OAAO,EAAE,KAAK,gBAAgB,EAA0C,MAAM,kBAAkB,CAAA;AA+BhG,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAY,eAAe,EAAE,MAAM,YAAY,CAAA;AAI5F,4EAA4E;AAC5E,KAAK,QAAQ,CAAC,SAAS,SAAS,cAAc,IAAI;IAChD,QAAQ,EAAE,SAAS,CAAA;IACnB,SAAS,EAAE,eAAe,CAAA;CAC3B,CAAA;AAuBD;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,gBAAgB,CAAA;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAA;IAEd,IAAI,EAAE,MAAM,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;CAC/D;AAED;;;;;;;;;;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;IAChD;;;;;OAKG;IACH,UAAU,EAAE,SAAS,EAAE,CAAA;IACvB;;;;;;OAMG;IACH,YAAY,EAAE,WAAW,EAAE,CAAA;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,SAAS,SAAS,cAAc,EACvD,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,GACjC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,GAAG,mBAAmB,CAAC,SAAS,CAAC,CA+f5D"}

package/dist/app.js

@@ -410,56 +410,79 @@ export function mountApp(config) {
     // them so the prefix logic is single-sourced here. Cheap array pushes — no
     // eager `import()` and no runtime read.
     const lazyMounts = [];
+    // Per-module OpenAPI generation manifest (voyant#2733). Recorded alongside the
+    // mount so the module name + real prefix are single-sourced here; `publicPath`
+    // overrides are captured with their actual mount, not re-derived. Eager routes
+    // are wrapped as `() => routes` so the generator's loader-based path is
+    // uniform across eager + lazy. Webhook routes are intentionally excluded — the
+    // per-module docs cover the admin/storefront surfaces only.
+    const moduleMounts = [];
     // 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);
+        const moduleName = mod.module.name;
+        const adminPrefix = `/v1/admin/${moduleName}`;
+        const publicPrefix = resolveSurfaceMountPath("/v1/public", mod.publicPath, moduleName);
         if (mod.adminRoutes) {
-            app.route(adminPrefix, mod.adminRoutes);
+            const adminRoutes = mod.adminRoutes;
+            app.route(adminPrefix, adminRoutes);
+            moduleMounts.push({ moduleName, prefix: adminPrefix, load: () => adminRoutes });
         }
         if (mod.publicRoutes) {
-            app.route(publicPrefix, mod.publicRoutes);
+            const publicRoutes = mod.publicRoutes;
+            app.route(publicPrefix, publicRoutes);
+            moduleMounts.push({ moduleName, prefix: publicPrefix, load: () => publicRoutes });
         }
         if (mod.lazyAdminRoutes) {
             mountLazyRoutesAt(app, adminPrefix, mod.lazyAdminRoutes);
             lazyMounts.push({ prefix: adminPrefix, load: mod.lazyAdminRoutes });
+            moduleMounts.push({ moduleName, prefix: adminPrefix, load: mod.lazyAdminRoutes });
         }
         if (mod.lazyPublicRoutes) {
             mountLazyRoutesAt(app, publicPrefix, mod.lazyPublicRoutes);
             lazyMounts.push({ prefix: publicPrefix, load: mod.lazyPublicRoutes });
+            moduleMounts.push({ moduleName, prefix: publicPrefix, load: mod.lazyPublicRoutes });
         }
         if (mod.lazyRoutes) {
             mountLazyRoutePaths(app, mod.lazyRoutes.paths, mod.lazyRoutes.load);
             lazyMounts.push({ prefix: "/", load: mod.lazyRoutes.load });
+            moduleMounts.push({ moduleName, prefix: "/", load: mod.lazyRoutes.load });
         }
         if (mod.webhookRoutes) {
-            app.route(`/v1/${mod.module.name}`, mod.webhookRoutes);
+            app.route(`/v1/${moduleName}`, mod.webhookRoutes);
         }
     }
     // 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);
+        const moduleName = ext.extension.module;
+        const adminPrefix = `/v1/admin/${moduleName}`;
+        const publicPrefix = resolveSurfaceMountPath("/v1/public", ext.publicPath, moduleName);
         if (ext.adminRoutes) {
-            app.route(adminPrefix, ext.adminRoutes);
+            const adminRoutes = ext.adminRoutes;
+            app.route(adminPrefix, adminRoutes);
+            moduleMounts.push({ moduleName, prefix: adminPrefix, load: () => adminRoutes });
         }
         if (ext.publicRoutes) {
-            app.route(publicPrefix, ext.publicRoutes);
+            const publicRoutes = ext.publicRoutes;
+            app.route(publicPrefix, publicRoutes);
+            moduleMounts.push({ moduleName, prefix: publicPrefix, load: () => publicRoutes });
         }
         if (ext.lazyAdminRoutes) {
             mountLazyRoutesAt(app, adminPrefix, ext.lazyAdminRoutes);
             lazyMounts.push({ prefix: adminPrefix, load: ext.lazyAdminRoutes });
+            moduleMounts.push({ moduleName, prefix: adminPrefix, load: ext.lazyAdminRoutes });
         }
         if (ext.lazyPublicRoutes) {
             mountLazyRoutesAt(app, publicPrefix, ext.lazyPublicRoutes);
             lazyMounts.push({ prefix: publicPrefix, load: ext.lazyPublicRoutes });
+            moduleMounts.push({ moduleName, prefix: publicPrefix, load: ext.lazyPublicRoutes });
         }
         if (ext.lazyRoutes) {
             mountLazyRoutePaths(app, ext.lazyRoutes.paths, ext.lazyRoutes.load);
             lazyMounts.push({ prefix: "/", load: ext.lazyRoutes.load });
+            moduleMounts.push({ moduleName, prefix: "/", load: ext.lazyRoutes.load });
         }
         if (ext.webhookRoutes) {
-            app.route(`/v1/${ext.extension.module}`, ext.webhookRoutes);
+            app.route(`/v1/${moduleName}`, ext.webhookRoutes);
         }
     }
     // Additional routes
@@ -477,6 +500,7 @@ export function mountApp(config) {
     const augmented = app;
     augmented.eventBus = eventBus;
     augmented.lazyMounts = lazyMounts;
+    augmented.moduleMounts = moduleMounts;
     augmented.ready = (bindings) => ensureRuntimeBootstrapped(bindings ?? {});
     return augmented;
 }

package/dist/openapi.d.ts

@@ -66,6 +66,23 @@ export interface LazyMount {
     prefix: string;
     load: LazyRoutesLoader;
 }
+/**
+ * A single module route mount recorded by `mountApp` for build-time per-module
+ * spec generation (voyant#2733). One module contributes several mounts (admin +
+ * public, eager + lazy), all tagged with the same `moduleName` — so the module
+ * boundary is the authoritative one from the registration, not a path-prefix
+ * guess. `prefix` is the real absolute mount (base path included), so the
+ * generated per-module doc carries correct absolute paths — including
+ * `publicPath` overrides whose prefix isn't the module name (e.g. a module that
+ * mounts its storefront routes under `/v1/public/booking-engine`). `load`
+ * returns the sub-app without serving it (eager mounts wrap the already-built
+ * app as `() => routes`; lazy mounts pass their loader).
+ */
+export interface ModuleMount {
+    moduleName: string;
+    prefix: string;
+    load: () => AnyApp | Promise<AnyApp>;
+}
 /**
  * Eager-merge lazy route families into a generated base document (voyant#2114).
  *
@@ -86,5 +103,81 @@ export interface LazyMount {
  * (`@asteasolutions/zod-to-openapi` stays out of the Worker bundle).
  */
 export declare function mergeLazyOpenApiPaths(base: OpenApiDocument, mounts: readonly LazyMount[], options: GenerateOpenApiOptions): Promise<OpenApiDocument>;
+/**
+ * Generate one self-contained OpenAPI document per module from its recorded
+ * mounts (voyant#2733).
+ *
+ * Instead of building one giant composed document and splitting it by path
+ * prefix, this generates each module's spec directly from the routes the module
+ * registered — the authoritative module boundary. Each module's admin + public
+ * (+ lazy) sub-apps are re-mounted into a throwaway `OpenAPIHono` at their real
+ * absolute prefix (reusing the exact prefix-merge `OpenAPIHono.route(...)`
+ * applies), then its `getOpenAPI31Document()` is read. The returned docs are
+ * self-contained (each carries its own referenced components), so they render
+ * and diff cleanly on their own — unlike a 7 MB aggregate.
+ *
+ * A mount whose loader throws, or that returns a plain `Hono` with no
+ * `.openapi()` registry, is skipped without failing the module. Modules that
+ * contribute no documented operation are omitted from the result entirely.
+ *
+ * Build-time only — same constraint as the rest of this module
+ * (`@asteasolutions/zod-to-openapi` must stay out of the Worker bundle).
+ */
+export declare function generateModuleOpenApiDocuments(mounts: readonly ModuleMount[], options: GenerateOpenApiOptions): Promise<Map<string, OpenApiDocument>>;
+/**
+ * Build the authoritative path → module ownership map from the mount manifest.
+ *
+ * Generates each module's isolated doc (see `generateModuleOpenApiDocuments`)
+ * only to learn which real absolute paths it owns — so `publicPath` overrides
+ * (whose prefix isn't the module name, e.g. `/v1/public/booking-engine`) map to
+ * the right module. Routes the manifest doesn't record (`additionalRoutes`,
+ * directly-mounted routes) are absent here and fall back to their path segment.
+ *
+ * Build-time only.
+ */
+export declare function buildModulePathOwnership(mounts: readonly ModuleMount[], options: GenerateOpenApiOptions): Promise<Map<string, string>>;
+/**
+ * Partition a composed document into one document per module, covering EVERY
+ * admin/storefront path (voyant#2733).
+ *
+ * Uses the ownership map as the authoritative module owner, falling back to the
+ * path's own segment for anything the manifest doesn't claim (e.g.
+ * `additionalRoutes` mounts like the operator's workflow-runs admin surface).
+ * The full surface is therefore partitioned exactly: every `/v1/admin/*` and
+ * `/v1/public/*` path lands in exactly one module document. Non-surface routes
+ * (`/v1/<name>` webhooks, legacy `/v1/*`) live only in the aggregate, as before.
+ *
+ * Each per-module document carries the aggregate's shared `components` verbatim
+ * (there is ~one), so it stays a valid, self-contained OpenAPI document.
+ */
+export declare function partitionByModule(full: OpenApiDocument, owner: ReadonlyMap<string, string>): Map<string, OpenApiDocument>;
+/**
+ * Convenience: build the ownership map and partition in one call. Prefer the
+ * two-step `buildModulePathOwnership` + `partitionByModule` when you also want
+ * to `stampModuleMetadata` the aggregate from the same map (so it's built once).
+ *
+ * Build-time only.
+ */
+export declare function splitDocumentByModule(full: OpenApiDocument, mounts: readonly ModuleMount[], options: GenerateOpenApiOptions): Promise<Map<string, OpenApiDocument>>;
+/**
+ * Stamp every operation with the metadata standard OpenAPI tooling expects
+ * (voyant#2733 / voyant#2729). All fields are non-destructive — a value a route
+ * already declares is never overwritten:
+ *   - `operationId` — stable camelCase id from method + path, for readable
+ *     generated client method names.
+ *   - `summary` — the method + path signature, so viewers/linters have a title
+ *     for every operation.
+ *   - `tags: [module]` — so Swagger/Scalar group the sidebar by module (they
+ *     key grouping off `tags` and ignore `x-*`).
+ *   - `x-voyant-module` / `x-voyant-surface` — machine-readable owner + surface
+ *     for custom tooling that shouldn't re-derive them from path prefixes.
+ *
+ * The module is the authoritative owner from the manifest, so `publicPath`
+ * overrides are labelled with their real owning module rather than their mount
+ * prefix. Applied to the aggregate before it's split, so the per-module and
+ * surface documents (all derived from it) inherit the stamps. Keys are appended,
+ * keeping order deterministic for the drift gate.
+ */
+export declare function stampModuleMetadata(doc: OpenApiDocument, owner: ReadonlyMap<string, string>): OpenApiDocument;
 export {};
 //# sourceMappingURL=openapi.d.ts.map

package/dist/openapi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAEhC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAExD;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8EAA8E;IAC9E,CAAC,SAAS,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAA;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,CAAC,SAAS,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAA;CACpC;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,WAAW,CAAA;IACjB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAA;CAC1B;AAGD,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AAEjC;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,WAAW,CAAC,sBAAsB,CAAC,CAAC,CAAA;AAE7E;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,sBAAsB,GAC9B,eAAe,CASjB;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,YAAY,CAAA;AAO/C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,UAAU,GAAG,eAAe,CAMxF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,gBAAgB,CAAA;CACvB;AAYD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,SAAS,SAAS,EAAE,EAC5B,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,CA8D1B"}
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAEhC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAExD;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8EAA8E;IAC9E,CAAC,SAAS,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAA;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,CAAC,SAAS,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAA;CACpC;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,WAAW,CAAA;IACjB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAA;CAC1B;AAGD,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AAEjC;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,WAAW,CAAC,sBAAsB,CAAC,CAAC,CAAA;AAE7E;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,sBAAsB,GAC9B,eAAe,CASjB;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,YAAY,CAAA;AAO/C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,UAAU,GAAG,eAAe,CAMxF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,gBAAgB,CAAA;CACvB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACrC;AAYD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,SAAS,SAAS,EAAE,EAC5B,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,CA8D1B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAsCvC;AAuBD;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAO9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAsB9B;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAEvC;AAyCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,eAAe,EACpB,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,eAAe,CAgDjB"}

package/dist/openapi.js

@@ -112,3 +112,253 @@ export async function mergeLazyOpenApiPaths(base, mounts, options) {
     }
     return merged;
 }
+/**
+ * Generate one self-contained OpenAPI document per module from its recorded
+ * mounts (voyant#2733).
+ *
+ * Instead of building one giant composed document and splitting it by path
+ * prefix, this generates each module's spec directly from the routes the module
+ * registered — the authoritative module boundary. Each module's admin + public
+ * (+ lazy) sub-apps are re-mounted into a throwaway `OpenAPIHono` at their real
+ * absolute prefix (reusing the exact prefix-merge `OpenAPIHono.route(...)`
+ * applies), then its `getOpenAPI31Document()` is read. The returned docs are
+ * self-contained (each carries its own referenced components), so they render
+ * and diff cleanly on their own — unlike a 7 MB aggregate.
+ *
+ * A mount whose loader throws, or that returns a plain `Hono` with no
+ * `.openapi()` registry, is skipped without failing the module. Modules that
+ * contribute no documented operation are omitted from the result entirely.
+ *
+ * Build-time only — same constraint as the rest of this module
+ * (`@asteasolutions/zod-to-openapi` must stay out of the Worker bundle).
+ */
+export async function generateModuleOpenApiDocuments(mounts, options) {
+    const byModule = new Map();
+    for (const mount of mounts) {
+        const list = byModule.get(mount.moduleName);
+        if (list)
+            list.push(mount);
+        else
+            byModule.set(mount.moduleName, [mount]);
+    }
+    const result = new Map();
+    for (const [moduleName, moduleMounts] of byModule) {
+        const throwaway = new OpenAPIHono();
+        let mountedAny = false;
+        for (const { prefix, load } of moduleMounts) {
+            let subApp;
+            try {
+                subApp = await load();
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.warn(`[voyant] openapi: module "${moduleName}" mount at "${prefix}" failed to load, skipping: ${message}`);
+                continue;
+            }
+            if (!isOpenApiHono(subApp))
+                continue;
+            throwaway.route(prefix === "/" ? "/" : prefix, subApp);
+            mountedAny = true;
+        }
+        if (!mountedAny)
+            continue;
+        const doc = throwaway.getOpenAPI31Document({
+            openapi: "3.1.0",
+            info: options.info,
+            ...(options.servers ? { servers: options.servers } : {}),
+        });
+        if (!doc.paths || Object.keys(doc.paths).length === 0)
+            continue;
+        result.set(moduleName, doc);
+    }
+    return result;
+}
+/**
+ * The module a path belongs to, given the authoritative owner map: the manifest
+ * owner if known (which is what keeps `publicPath` overrides correct), else the
+ * path's own module segment — `<seg>` in `/v1/admin/<seg>/...`,
+ * `/v1/public/<seg>/...`, or `/v1/<seg>/...` (webhooks/legacy).
+ */
+function moduleNameForPath(path, owner) {
+    const known = owner.get(path);
+    if (known)
+        return known;
+    const parts = path.split("/").filter(Boolean); // ["v1","admin","bookings",...]
+    const seg = parts[1] === "admin" || parts[1] === "public" ? parts[2] : parts[1];
+    return seg ?? "misc";
+}
+/** The API surface a path is served on, or `null` for non-surface routes. */
+function surfaceForPath(path) {
+    if (path.startsWith("/v1/admin/"))
+        return "admin";
+    if (path.startsWith("/v1/public/"))
+        return "storefront";
+    return null;
+}
+/**
+ * Build the authoritative path → module ownership map from the mount manifest.
+ *
+ * Generates each module's isolated doc (see `generateModuleOpenApiDocuments`)
+ * only to learn which real absolute paths it owns — so `publicPath` overrides
+ * (whose prefix isn't the module name, e.g. `/v1/public/booking-engine`) map to
+ * the right module. Routes the manifest doesn't record (`additionalRoutes`,
+ * directly-mounted routes) are absent here and fall back to their path segment.
+ *
+ * Build-time only.
+ */
+export async function buildModulePathOwnership(mounts, options) {
+    const moduleDocs = await generateModuleOpenApiDocuments(mounts, options);
+    const owner = new Map();
+    for (const [moduleName, doc] of moduleDocs) {
+        for (const path of Object.keys(doc.paths ?? {}))
+            owner.set(path, moduleName);
+    }
+    return owner;
+}
+/**
+ * Partition a composed document into one document per module, covering EVERY
+ * admin/storefront path (voyant#2733).
+ *
+ * Uses the ownership map as the authoritative module owner, falling back to the
+ * path's own segment for anything the manifest doesn't claim (e.g.
+ * `additionalRoutes` mounts like the operator's workflow-runs admin surface).
+ * The full surface is therefore partitioned exactly: every `/v1/admin/*` and
+ * `/v1/public/*` path lands in exactly one module document. Non-surface routes
+ * (`/v1/<name>` webhooks, legacy `/v1/*`) live only in the aggregate, as before.
+ *
+ * Each per-module document carries the aggregate's shared `components` verbatim
+ * (there is ~one), so it stays a valid, self-contained OpenAPI document.
+ */
+export function partitionByModule(full, owner) {
+    const buckets = new Map();
+    for (const [path, item] of Object.entries(full.paths ?? {})) {
+        if (!path.startsWith("/v1/admin/") && !path.startsWith("/v1/public/"))
+            continue;
+        const moduleName = moduleNameForPath(path, owner);
+        let bucket = buckets.get(moduleName);
+        if (!bucket) {
+            bucket = {};
+            buckets.set(moduleName, bucket);
+        }
+        bucket[path] = item;
+    }
+    const result = new Map();
+    for (const [moduleName, paths] of buckets) {
+        result.set(moduleName, {
+            ...full,
+            paths,
+            ...(full.components ? { components: full.components } : {}),
+        });
+    }
+    return result;
+}
+/**
+ * Convenience: build the ownership map and partition in one call. Prefer the
+ * two-step `buildModulePathOwnership` + `partitionByModule` when you also want
+ * to `stampModuleMetadata` the aggregate from the same map (so it's built once).
+ *
+ * Build-time only.
+ */
+export async function splitDocumentByModule(full, mounts, options) {
+    return partitionByModule(full, await buildModulePathOwnership(mounts, options));
+}
+const HTTP_METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+/** PascalCase a path segment, splitting on non-alphanumerics (kebab, etc.). */
+function pascalCase(segment) {
+    return segment
+        .split(/[^a-zA-Z0-9]+/)
+        .filter(Boolean)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join("");
+}
+/**
+ * Stable camelCase operationId derived from method + path (voyant#2729) — gives
+ * client generators readable, deterministic method names instead of guessing.
+ * Path params render as `ByX`, the `v1` prefix is dropped:
+ * `GET /v1/admin/bookings/{id}` → `getAdminBookingsById`. Method + path is unique
+ * per OpenAPI, so the derived id is too (a numeric suffix guards edge cases).
+ */
+function deriveOperationId(method, path) {
+    const parts = path
+        .split("/")
+        .filter(Boolean)
+        .filter((segment) => segment !== "v1")
+        .map((segment) => {
+        const param = /^\{(.+)\}$/.exec(segment);
+        return param?.[1] ? `By${pascalCase(param[1])}` : pascalCase(segment);
+    });
+    return `${method}${parts.join("")}`;
+}
+/**
+ * A readable, always-correct operation summary (voyant#2729): the method + path
+ * signature. Deliberately mechanical rather than guessed prose — a hand-authored
+ * per-route `summary` overrides it (forward-only).
+ */
+function deriveSummary(method, path) {
+    return `${method.toUpperCase()} ${path}`;
+}
+/**
+ * Stamp every operation with the metadata standard OpenAPI tooling expects
+ * (voyant#2733 / voyant#2729). All fields are non-destructive — a value a route
+ * already declares is never overwritten:
+ *   - `operationId` — stable camelCase id from method + path, for readable
+ *     generated client method names.
+ *   - `summary` — the method + path signature, so viewers/linters have a title
+ *     for every operation.
+ *   - `tags: [module]` — so Swagger/Scalar group the sidebar by module (they
+ *     key grouping off `tags` and ignore `x-*`).
+ *   - `x-voyant-module` / `x-voyant-surface` — machine-readable owner + surface
+ *     for custom tooling that shouldn't re-derive them from path prefixes.
+ *
+ * The module is the authoritative owner from the manifest, so `publicPath`
+ * overrides are labelled with their real owning module rather than their mount
+ * prefix. Applied to the aggregate before it's split, so the per-module and
+ * surface documents (all derived from it) inherit the stamps. Keys are appended,
+ * keeping order deterministic for the drift gate.
+ */
+export function stampModuleMetadata(doc, owner) {
+    const paths = {};
+    // operationId must be unique across the document; track what we've assigned
+    // (including route-declared ids) so a derived id never collides.
+    const usedOperationIds = new Set();
+    for (const [path, item] of Object.entries(doc.paths ?? {})) {
+        if (!item || typeof item !== "object") {
+            paths[path] = item;
+            continue;
+        }
+        const moduleName = moduleNameForPath(path, owner);
+        const surface = surfaceForPath(path);
+        const nextItem = { ...item };
+        for (const method of HTTP_METHODS) {
+            const op = nextItem[method];
+            if (!op || typeof op !== "object")
+                continue;
+            const operation = op;
+            const declaredId = typeof operation.operationId === "string" && operation.operationId.length > 0
+                ? operation.operationId
+                : null;
+            let operationId = declaredId ?? deriveOperationId(method, path);
+            if (!declaredId) {
+                let suffix = 2;
+                while (usedOperationIds.has(operationId)) {
+                    operationId = `${deriveOperationId(method, path)}_${suffix++}`;
+                }
+            }
+            usedOperationIds.add(operationId);
+            const hasSummary = typeof operation.summary === "string" && operation.summary.length > 0;
+            // Swagger/Scalar group by `tags` (and ignore `x-*`) — without one a
+            // whole-surface document collapses under a single "default" group (#2733).
+            const hasTags = Array.isArray(operation.tags) && operation.tags.length > 0;
+            nextItem[method] = {
+                ...operation,
+                operationId,
+                ...(hasSummary ? {} : { summary: deriveSummary(method, path) }),
+                ...(hasTags ? {} : { tags: [moduleName] }),
+                "x-voyant-module": moduleName,
+                ...(surface ? { "x-voyant-surface": surface } : {}),
+            };
+        }
+        paths[path] = nextItem;
+    }
+    return { ...doc, paths };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyant-travel/hono",
-  "version": "0.118.4",
+  "version": "0.120.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -140,14 +140,14 @@
     "@voyant-travel/storage": "^0.106.0",
     "@voyant-travel/types": "^0.106.1",
     "@voyant-travel/utils": "^0.105.5",
-    "@voyant-travel/workflows": "^0.111.12"
+    "@voyant-travel/workflows": "^0.111.14"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260628.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9",
     "@voyant-travel/voyant-typescript-config": "^0.1.0",
-    "@voyant-travel/workflows-orchestrator": "^0.111.12"
+    "@voyant-travel/workflows-orchestrator": "^0.111.14"
   },
   "files": [
     "dist"