@silkweave/nestjs 1.11.0 → 2.0.0

package/src/lib/reflect/params.ts

@@ -0,0 +1,63 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { ROUTE_ARGS_METADATA } from '@nestjs/common/constants.js'
+
+/**
+ * `RouteParamtypes` numeric values from `@nestjs/common` (re-declared to avoid a
+ * value import of an internal enum). These are how `@Param`/`@Query`/`@Body`/...
+ * tag each handler argument in `ROUTE_ARGS_METADATA`.
+ */
+export const PARAMTYPE = {
+  REQUEST: 0,
+  RESPONSE: 1,
+  NEXT: 2,
+  BODY: 3,
+  QUERY: 4,
+  PARAM: 5,
+  HEADERS: 6,
+  SESSION: 7,
+  FILE: 8,
+  FILES: 9,
+  HOST: 10,
+  IP: 11,
+  RAW_BODY: 12
+} as const
+
+export interface ParamSlot {
+  /** `PARAMTYPE` value - which decorator tagged this argument. */
+  paramtype: number
+  /** Handler argument position. */
+  index: number
+  /** Decorator sub-key: `@Param('id')` → `'id'`; a bare `@Body()` → `undefined`. */
+  data?: string
+  /** Parameter-bound pipes (`@Param('id', ParseIntPipe)`). */
+  pipes: unknown[]
+  /** TypeScript-emitted constructor at this position (e.g. `String`, `CreateDto`). */
+  designType?: unknown
+}
+
+/**
+ * Read and normalise the route-argument metadata for a controller method.
+ * Returns one {@link ParamSlot} per decorated handler argument, sorted by
+ * argument index.
+ */
+export function readParamSlots(classRef: any, methodName: string, proto: any): ParamSlot[] {
+  const raw = Reflect.getMetadata(ROUTE_ARGS_METADATA, classRef, methodName) as
+    Record<string, { index: number; data?: unknown; pipes?: unknown[] }> | undefined
+  if (!raw) { return [] }
+  const designTypes = (Reflect.getMetadata('design:paramtypes', proto, methodName) as unknown[] | undefined) ?? []
+
+  const slots: ParamSlot[] = []
+  for (const key of Object.keys(raw)) {
+    const entry = raw[key]
+    const paramtype = Number(key.split(':')[0])
+    if (Number.isNaN(paramtype)) { continue }
+    slots.push({
+      paramtype,
+      index: entry.index,
+      data: typeof entry.data === 'string' ? entry.data : undefined,
+      pipes: entry.pipes ?? [],
+      designType: designTypes[entry.index]
+    })
+  }
+  return slots.sort((a, b) => a.index - b.index)
+}

package/src/lib/reflect/route.ts

@@ -0,0 +1,58 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { PATH_METADATA, METHOD_METADATA } from '@nestjs/common/constants.js'
+
+/**
+ * `RequestMethod` numeric values (from `@nestjs/common`) mapped to verbs. We
+ * map our own table rather than importing the enum to avoid pulling a value
+ * import for a handful of constants.
+ */
+const REQUEST_METHOD: Record<number, string> = {
+  0: 'GET',
+  1: 'POST',
+  2: 'PUT',
+  3: 'DELETE',
+  4: 'PATCH',
+  6: 'OPTIONS',
+  7: 'HEAD'
+}
+
+export interface RouteInfo {
+  /** HTTP verb (`GET`/`POST`/...). `PATCH` and others outside the REST set fall back to `POST`-ish handling by callers. */
+  method: string
+  /** Full route template in Nest form, e.g. `sessions/:sessionId/channels/:channelId` (no leading slash). */
+  path: string
+  /** Full route template in OpenAPI form, e.g. `/sessions/{sessionId}/channels/{channelId}`. */
+  openapiPath: string
+  /** Names of the `:param` placeholders across controller + method path. */
+  pathParams: string[]
+}
+
+function normalizeSegment(value: unknown): string {
+  if (typeof value !== 'string') { return '' }
+  return value.replace(/^\/+/, '').replace(/\/+$/, '')
+}
+
+function joinPath(...segments: string[]): string {
+  return segments.map(normalizeSegment).filter(Boolean).join('/')
+}
+
+/**
+ * Resolve the composed route (controller prefix + method path), HTTP verb, and
+ * path-param names for a decorated controller method, reading Nest's own
+ * `PATH_METADATA`/`METHOD_METADATA` reflection.
+ */
+export function reflectRoute(classRef: any, method: (...args: any[]) => any): RouteInfo {
+  const classPath = Reflect.getMetadata(PATH_METADATA, classRef) as string | string[] | undefined
+  const methodPath = Reflect.getMetadata(PATH_METADATA, method) as string | string[] | undefined
+  const verbCode = Reflect.getMetadata(METHOD_METADATA, method) as number | undefined
+
+  const classSeg = Array.isArray(classPath) ? (classPath[0] ?? '') : (classPath ?? '')
+  const methodSeg = Array.isArray(methodPath) ? (methodPath[0] ?? '') : (methodPath ?? '')
+  const path = joinPath(classSeg, methodSeg)
+  const httpMethod = REQUEST_METHOD[verbCode ?? 0] ?? 'GET'
+
+  const pathParams = [...path.matchAll(/:([A-Za-z0-9_]+)/g)].map((m) => m[1])
+  const openapiPath = `/${path.replace(/:([A-Za-z0-9_]+)/g, '{$1}')}`
+
+  return { method: httpMethod, path, openapiPath, pathParams }
+}

package/src/lib/reflect/schema.ts

@@ -0,0 +1,270 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-explicit-any */
+import { z } from 'zod/v4'
+import { classValidatorMetas } from './classValidator.js'
+
+/** `@nestjs/swagger` reflect-metadata keys. Read directly so swagger stays an optional peer. */
+const API_MODEL_PROPERTIES = 'swagger/apiModelProperties'
+const API_MODEL_PROPERTIES_ARRAY = 'swagger/apiModelPropertiesArray'
+
+/**
+ * A transport-neutral description of a single input field. Every metadata
+ * source (swagger decorators, class-validator, an OpenAPI document, TypeScript
+ * `design:type`) is mapped to this shape, the shapes are merged by precedence,
+ * and the result is converted to Zod once. Keeping a single intermediate keeps
+ * the per-source mappers small and the Zod construction in one place.
+ */
+export interface FieldDesc {
+  type?: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'unknown'
+  required?: boolean
+  description?: string
+  enum?: (string | number)[]
+  items?: FieldDesc
+  min?: number
+  max?: number
+  minLength?: number
+  maxLength?: number
+  format?: string
+  default?: unknown
+}
+
+/** Strip `undefined` values so a later source never clobbers an earlier one with a hole. */
+function defined<T extends object>(obj: T): Partial<T> {
+  const out: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined) { out[k] = v }
+  }
+  return out as Partial<T>
+}
+
+/** Merge `over` onto `base` - defined keys of `over` win. */
+export function mergeField(base: FieldDesc, over: FieldDesc): FieldDesc {
+  return { ...base, ...defined(over) }
+}
+
+function enumToZod(values: (string | number)[]): z.ZodType {
+  const strings = values.filter((v): v is string => typeof v === 'string')
+  if (strings.length === values.length && strings.length > 0) {
+    return z.enum(strings as [string, ...string[]])
+  }
+  const literals = values.map((v) => z.literal(v))
+  if (literals.length === 0) { return z.unknown() }
+  if (literals.length === 1) { return literals[0] }
+  return z.union(literals as unknown as [z.ZodType, z.ZodType, ...z.ZodType[]])
+}
+
+function baseToZod(d: FieldDesc): z.ZodType {
+  switch (d.type) {
+    case 'string': {
+      let s = z.string()
+      if (d.minLength != null) { s = s.min(d.minLength) }
+      if (d.maxLength != null) { s = s.max(d.maxLength) }
+      return s
+    }
+    case 'integer':
+    case 'number': {
+      let n = z.number()
+      if (d.type === 'integer') { n = n.int() }
+      if (d.min != null) { n = n.min(d.min) }
+      if (d.max != null) { n = n.max(d.max) }
+      return n
+    }
+    case 'boolean':
+      return z.boolean()
+    case 'array':
+      return z.array(d.items ? fieldToZod({ ...d.items, required: true }) : z.unknown())
+    case 'object':
+      return z.record(z.string(), z.unknown())
+    default:
+      return z.unknown()
+  }
+}
+
+/** Convert a merged {@link FieldDesc} to a Zod schema. */
+export function fieldToZod(d: FieldDesc): z.ZodType {
+  let schema = (d.enum?.length) ? enumToZod(d.enum) : baseToZod(d)
+  if (d.description) { schema = schema.describe(d.description) }
+  if (d.default !== undefined) {
+    schema = (schema as any).default(d.default)
+  } else if (d.required === false) {
+    schema = schema.optional()
+  }
+  return schema
+}
+
+// --- per-source mappers ---------------------------------------------------
+
+/** Normalise a TS-enum object or an array literal to a flat value list. */
+export function normalizeEnum(value: unknown): (string | number)[] | undefined {
+  if (Array.isArray(value)) {
+    return value.filter((v): v is string | number => typeof v === 'string' || typeof v === 'number')
+  }
+  if (value && typeof value === 'object') {
+    return Object.values(value).filter((v): v is string | number => typeof v === 'string' || typeof v === 'number')
+  }
+  return undefined
+}
+
+/** Map a swagger/`design:type` type token (constructor, `[Type]`, or string) to a base type. */
+export function typeTokenToBase(type: unknown): FieldDesc['type'] | undefined {
+  if (type == null) { return undefined }
+  if (type === String) { return 'string' }
+  if (type === Number) { return 'number' }
+  if (type === Boolean) { return 'boolean' }
+  if (type === Array) { return 'array' }
+  if (type === Date) { return 'string' }
+  if (Array.isArray(type)) { return 'array' }
+  if (typeof type === 'string') {
+    const t = type.toLowerCase()
+    if (t === 'string' || t === 'number' || t === 'integer' || t === 'boolean' || t === 'array' || t === 'object') {
+      return t
+    }
+  }
+  return undefined
+}
+
+/** From the constructor TypeScript emits via `emitDecoratorMetadata`. */
+export function designTypeToField(ctor: unknown): FieldDesc {
+  const type = typeTokenToBase(ctor)
+  const f: FieldDesc = {}
+  if (type) { f.type = type }
+  return f
+}
+
+/** From an `@ApiParam`/`@ApiQuery` entry stored under `swagger/apiParameters`. */
+export function swaggerParamToField(p: Record<string, any>): FieldDesc {
+  const f: FieldDesc = {}
+  if (p['description']) { f.description = p['description'] }
+  if (typeof p['required'] === 'boolean') { f.required = p['required'] }
+  const type = typeTokenToBase(p['type'])
+  if (type) { f.type = type }
+  if (p['isArray']) { f.type = 'array' }
+  const en = normalizeEnum(p['enum'])
+  if (en) { f.enum = en }
+  if (p['schema'] && typeof p['schema'] === 'object') {
+    return mergeField(f, openapiSchemaToField(p['schema']))
+  }
+  return f
+}
+
+/** From an `@ApiProperty` options object stored under `swagger/apiModelProperties`. */
+export function apiPropertyToField(o: Record<string, any>): FieldDesc {
+  const f: FieldDesc = {}
+  if (o['description']) { f.description = o['description'] }
+  if (typeof o['required'] === 'boolean') { f.required = o['required'] }
+  const type = typeTokenToBase(o['type'])
+  if (type) { f.type = type }
+  if (o['isArray']) {
+    f.items = { type: type && type !== 'array' ? type : 'unknown' }
+    f.type = 'array'
+  }
+  const en = normalizeEnum(o['enum'])
+  if (en) { f.enum = en }
+  if (o['minimum'] != null) { f.min = o['minimum'] }
+  if (o['maximum'] != null) { f.max = o['maximum'] }
+  if (o['minLength'] != null) { f.minLength = o['minLength'] }
+  if (o['maxLength'] != null) { f.maxLength = o['maxLength'] }
+  if (o['format']) { f.format = o['format'] }
+  if (o['default'] !== undefined) { f.default = o['default'] }
+  return f
+}
+
+/** `class-validator` decorator type → field base type. */
+const CV_TYPE: Record<string, FieldDesc['type']> = {
+  isString: 'string',
+  isInt: 'integer',
+  isBoolean: 'boolean',
+  isArray: 'array'
+}
+
+/** `class-validator` decorator type → numeric-constraint field key. */
+const CV_NUMERIC: Record<string, 'min' | 'max' | 'minLength' | 'maxLength'> = {
+  min: 'min',
+  max: 'max',
+  minLength: 'minLength',
+  maxLength: 'maxLength'
+}
+
+/**
+ * Fold one `class-validator` metadata entry into the field descriptor. Built-in
+ * validators record their identity in `name` (`isString`, `minLength`, ...) with
+ * `type: 'customValidation'`; `@IsOptional` uses `name: 'isOptional'`. We key off
+ * `name`, falling back to `type`.
+ */
+function applyValidationMeta(f: FieldDesc, meta: { type?: string; name?: string; constraints?: unknown[] }): void {
+  const key = meta.name ?? meta.type
+  if (!key) { return }
+  if (key in CV_TYPE) { f.type = CV_TYPE[key]; return }
+  const c0 = meta.constraints?.[0]
+  if (key in CV_NUMERIC) {
+    if (typeof c0 === 'number') { f[CV_NUMERIC[key]] = c0 }
+    return
+  }
+  if (key === 'isNumber') { if (!f.type) { f.type = 'number' } return }
+  if (key === 'isEmail') { if (!f.type) { f.type = 'string' } f.format = 'email'; return }
+  if (key === 'isDate' || key === 'isDateString') { f.type = 'string'; f.format = 'date-time'; return }
+  if (key === 'isEnum') { const e = normalizeEnum(c0); if (e) { f.enum = e } return }
+  if (key === 'isOptional') { f.required = false }
+}
+
+/** From an array of `class-validator` validation-metadata entries for one property. */
+export function classValidatorToField(metas: Array<{ type?: string; name?: string; constraints?: unknown[] }>): FieldDesc {
+  const f: FieldDesc = {}
+  for (const meta of metas) { applyValidationMeta(f, meta) }
+  return f
+}
+
+/** From an OpenAPI Schema Object (used by both the doc and `@ApiParam({ schema })`). */
+export function openapiSchemaToField(schema: Record<string, any>): FieldDesc {
+  const f: FieldDesc = {}
+  const type = typeof schema['type'] === 'string' ? schema['type'].toLowerCase() : undefined
+  if (type === 'string' || type === 'number' || type === 'integer' || type === 'boolean' || type === 'array' || type === 'object') {
+    f.type = type
+  }
+  if (schema['description']) { f.description = schema['description'] }
+  const en = normalizeEnum(schema['enum'])
+  if (en) { f.enum = en }
+  if (schema['minimum'] != null) { f.min = schema['minimum'] }
+  if (schema['maximum'] != null) { f.max = schema['maximum'] }
+  if (schema['minLength'] != null) { f.minLength = schema['minLength'] }
+  if (schema['maxLength'] != null) { f.maxLength = schema['maxLength'] }
+  if (schema['format']) { f.format = schema['format'] }
+  if (schema['default'] !== undefined) { f.default = schema['default'] }
+  if (schema['items'] && typeof schema['items'] === 'object') {
+    f.items = openapiSchemaToField(schema['items'])
+  }
+  return f
+}
+
+/**
+ * Reflect a whole-DTO class (`@Body() dto: CreateDto`) into per-property
+ * {@link FieldDesc}s. Property names are the union of `@ApiProperty` and
+ * `class-validator` decorated fields; each field merges `design:type` (base),
+ * then `class-validator` constraints, then `@ApiProperty` (highest). Properties
+ * default to required unless a source marks them optional.
+ */
+export function reflectDtoFields(dtoType: any): Record<string, FieldDesc> {
+  const proto = dtoType?.prototype
+  if (!proto) { return {} }
+  const cvMetas = classValidatorMetas(dtoType)
+
+  const names = new Set<string>()
+  const swaggerArray = (Reflect.getMetadata(API_MODEL_PROPERTIES_ARRAY, proto) as string[] | undefined) ?? []
+  for (const entry of swaggerArray) { names.add(entry.replace(/^:/, '')) }
+  for (const name of Object.keys(cvMetas)) { names.add(name) }
+
+  const out: Record<string, FieldDesc> = {}
+  for (const name of names) {
+    let f = designTypeToField(Reflect.getMetadata('design:type', proto, name))
+    if (cvMetas[name]) { f = mergeField(f, classValidatorToField(cvMetas[name])) }
+    const apiProp = Reflect.getMetadata(API_MODEL_PROPERTIES, proto, name) as Record<string, any> | undefined
+    if (apiProp) {
+      const fromApi = apiPropertyToField(apiProp)
+      // `@ApiProperty` is required unless `required: false` is explicit.
+      if (fromApi.required === undefined && apiProp['required'] === undefined) { fromApi.required = true }
+      f = mergeField(f, fromApi)
+    }
+    if (f.required === undefined) { f.required = true }
+    out[name] = f
+  }
+  return out
+}

package/src/lib/reflect/swagger.ts

@@ -0,0 +1,39 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { FieldDesc } from './schema.js'
+import { swaggerParamToField } from './schema.js'
+
+/** `@nestjs/swagger` reflect-metadata keys (read directly - swagger is an optional peer). */
+const API_OPERATION = 'swagger/apiOperation'
+const API_PARAMETERS = 'swagger/apiParameters'
+
+export interface OperationMeta {
+  /** Tool-description candidate from `@ApiOperation({ summary | description })`. */
+  description?: string
+  /** Per-name `FieldDesc` reflected from `@ApiParam`/`@ApiQuery` entries. */
+  params: Record<string, FieldDesc>
+}
+
+/**
+ * Read operation-level `@nestjs/swagger` metadata off a controller method:
+ * `@ApiOperation` (summary/description) and the `@ApiParam`/`@ApiQuery` array
+ * (each describing one path/query field). Returns empty data when swagger
+ * decorators are absent.
+ */
+export function reflectOperation(method: (...args: any[]) => any): OperationMeta {
+  const operation = Reflect.getMetadata(API_OPERATION, method) as Record<string, any> | undefined
+  const description = operation
+    ? (typeof operation['summary'] === 'string' && operation['summary']
+      ? operation['summary']
+      : (typeof operation['description'] === 'string' ? operation['description'] : undefined))
+    : undefined
+
+  const parameters = (Reflect.getMetadata(API_PARAMETERS, method) as Array<Record<string, any>> | undefined) ?? []
+  const params: Record<string, FieldDesc> = {}
+  for (const p of parameters) {
+    const name = typeof p['name'] === 'string' ? p['name'] : undefined
+    if (!name) { continue }
+    params[name] = swaggerParamToField(p)
+  }
+
+  return { description, params }
+}

package/src/lib/silkweave.module.ts

@@ -1,19 +1,22 @@
 import { Inject, Module, type DynamicModule, type MiddlewareConsumer, type NestModule } from '@nestjs/common'
 import { DiscoveryModule, HttpAdapterHost } from '@nestjs/core'
 import { createContext } from '@silkweave/core'
-import { ActionDiscovery } from './discovery.js'
+import { ControllerDiscovery } from './controllerDiscovery.js'
 import { SILKWEAVE_MODULE_OPTIONS, type SilkweaveModuleOptions } from './types.js'
 
 /**
  * Root module for `@silkweave/nestjs`.
  *
- * Discovers every `@Action`-decorated method via `DiscoveryService` and
- * registers the configured adapters (`rest()`, `trpc()`, `mcp()`) directly on
- * Nest's HTTP adapter inside `configure()`. Because `configure()` runs during
- * `registerModules` - before Nest's `registerRouter()` step - Silkweave's
- * routes always sit ahead of every controller in the Express stack. There is
- * no slot middleware, no race with Nest's 404 catch-all, and every route
- * shows up in Nest's `RoutesResolver` logger.
+ * Discovers every `@Mcp`-decorated **controller method** via `DiscoveryService`,
+ * reflects each into a Silkweave action (input schema from the route + parameter
+ * decorators + optional OpenAPI document; invocation by re-binding the validated
+ * input back into the method), and registers the configured adapter(s) - `mcp()` -
+ * directly on Nest's HTTP adapter inside `configure()`.
+ *
+ * Because `configure()` runs during `registerModules` - before Nest's
+ * `registerRouter()` step - Silkweave's routes always sit ahead of every
+ * controller in the Express stack. The controllers keep serving HTTP exactly as
+ * before; `@Mcp` is purely additive.
  *
  * @example
  * ```ts
@@ -21,13 +24,10 @@ import { SILKWEAVE_MODULE_OPTIONS, type SilkweaveModuleOptions } from './types.j
  *   imports: [
  *     SilkweaveModule.forRoot({
  *       silkweave: { name: 'app', description: 'My App', version: '1.0.0' },
- *       adapters: [
- *         rest({ basePath: '/api' }),
- *         trpc({ basePath: '/trpc' }),
- *         mcp({ basePath: '/mcp' })
- *       ]
+ *       adapters: [mcp({ basePath: '/mcp' })]
  *     })
- *   ]
+ *   ],
+ *   controllers: [ChannelsController]
  * })
  * export class AppModule {}
  * ```
@@ -36,7 +36,7 @@ import { SILKWEAVE_MODULE_OPTIONS, type SilkweaveModuleOptions } from './types.j
 export class SilkweaveModule implements NestModule {
   constructor(
     @Inject(SILKWEAVE_MODULE_OPTIONS) private readonly options: SilkweaveModuleOptions,
-    private readonly discovery: ActionDiscovery,
+    private readonly discovery: ControllerDiscovery,
     private readonly httpAdapterHost: HttpAdapterHost
   ) { }
 
@@ -47,7 +47,7 @@ export class SilkweaveModule implements NestModule {
       imports: [DiscoveryModule],
       providers: [
         { provide: SILKWEAVE_MODULE_OPTIONS, useValue: options },
-        ActionDiscovery
+        ControllerDiscovery
       ],
       exports: []
     }
@@ -58,7 +58,7 @@ export class SilkweaveModule implements NestModule {
     if (!httpAdapter) {
       throw new Error('@silkweave/nestjs: HttpAdapterHost.httpAdapter is not available.')
     }
-    const allActions = this.discovery.discover()
+    const allActions = this.discovery.discover(this.options.openapi)
     for (const adapter of this.options.adapters) {
       const baseContext = createContext({ ...(this.options.context ?? {}), adapter: adapter.name })
       const actions = adapter.allActions

package/src/lib/types.ts

@@ -1,5 +1,6 @@
 import type { HttpAdapterHost } from '@nestjs/core'
 import type { Action, SilkweaveContext, SilkweaveOptions } from '@silkweave/core'
+import type { OpenApiDocument } from './reflect/openapi.js'
 
 /**
  * Context passed to a Nest Silkweave adapter when `SilkweaveModule` wires it
@@ -28,12 +29,13 @@ export interface NestAdapterRegisterContext {
  */
 export interface NestSilkweaveAdapter {
   /** Adapter discriminator - set on the silkweave context as `ctx.get('adapter')`. */
-  readonly name: 'rest' | 'trpc' | 'mcp' | 'typegen'
+  readonly name: 'mcp'
+  /** URL prefix the adapter mounts on (e.g. `'/mcp'`). Surfaced for introspection. */
+  readonly basePath?: string
   /**
    * When `true`, the adapter receives every discovered action regardless of
-   * each action's `transports` allowlist / `isEnabled` gate. Used by
-   * non-runtime adapters like `typegen()` that emit types for the entire
-   * action surface.
+   * each action's `isEnabled` gate. Reserved for non-runtime adapters that need
+   * the entire action surface.
    */
   readonly allActions?: boolean
   /** Register this adapter's routes on Nest's HTTP server. */
@@ -43,10 +45,17 @@ export interface NestSilkweaveAdapter {
 export interface SilkweaveModuleOptions {
   /** Identity for the silkweave instance - surfaced to MCP clients, OpenAPI, etc. */
   silkweave: SilkweaveOptions
-  /** Adapters to mount. Examples: `rest()`, `trpc()`, `mcp()`. */
+  /** Adapters to mount. Currently `mcp()`. */
   adapters: NestSilkweaveAdapter[]
   /** Initial context keys merged into every adapter's `baseContext`. */
   context?: Record<string, unknown>
+  /**
+   * Optional OpenAPI document (e.g. from `SwaggerModule.createDocument(app, cfg)`)
+   * used as an authoritative source when reflecting `@Mcp` tool input schemas.
+   * Matched to each method by HTTP verb + path; falls back to decorator
+   * reflection when an operation or field isn't present.
+   */
+  openapi?: OpenApiDocument
 }
 
 export const SILKWEAVE_MODULE_OPTIONS = '__silkweave_module_options__'