@forinda/kickjs 5.17.0 → 5.18.0-alpha.1

package/dist/adapter-D_uzU-QA.d.mts

@@ -0,0 +1,2121 @@
+
+import { i as Constructor, o as MaybePromise } from "./interfaces-DbTyKGdS.mjs";
+import { s as InjectionToken, t as Container } from "./container-TWOUyR_0.mjs";
+import { O as RouteDefinition, g as FileUploadConfig, x as MiddlewareHandler } from "./decorators-ejABLo9H.mjs";
+import { _ as ExecutionContext, a as AnyContributorRegistration, d as ContributorRegistrations, r as AppModuleEntry, t as AppModule, v as MetaValue } from "./app-module-CuAS6hJC.mjs";
+import { i as ProblemDetails } from "./errors-n0H96eEz.mjs";
+import { S as QueryFieldConfig, T as TypedParsedQuery, t as ParseQueryOptions } from "./index-BtWJ9SLP.mjs";
+import http, { IncomingMessage, ServerResponse } from "node:http";
+import { ErrorRequestHandler, Express as Express$1, NextFunction, Request, RequestHandler, Response } from "express";
+
+//#region src/core/introspect.d.ts
+/**
+ * Per-primitive introspection snapshot — the JSON shape an adapter or
+ * plugin's optional `introspect()` hook returns for DevTools.
+ *
+ * Lives in `@forinda/kickjs` (not `@forinda/kickjs-devtools-kit`) so
+ * adopters can type their `introspect()` return without taking on a
+ * dep on the kit just to satisfy the contract. The kit's own
+ * `IntrospectionSnapshot` type is structurally identical and continues
+ * to be the canonical doc location for DevTools-side consumers; the
+ * two stay in lockstep — if a field is added on one side it MUST be
+ * added on the other (covered by the type-equivalence test in the
+ * devtools-kit package).
+ *
+ * Cheap-by-default principle: `state` and `metrics` should be O(1) to
+ * compute (counters, flags, recent samples). Anything that requires a
+ * DB round trip or a full DI graph walk belongs behind a separate
+ * explicit RPC — DevTools polls topology aggressively.
+ */
+interface IntrospectionSnapshot {
+  /**
+   * Wire-protocol version this snapshot conforms to. The kit ships a
+   * `PROTOCOL_VERSION` constant typed as the literal `1`; we mirror
+   * that literal here so structural parity is enforced both ways —
+   * an adopter who writes `protocolVersion: 1` satisfies both this
+   * type and the kit's `IntrospectionSnapshot`. Bumping is a
+   * coordinated kit + framework release; widen this literal in
+   * lockstep.
+   */
+  protocolVersion: 1;
+  /** Stable identity matching the `name` from `definePlugin` / `defineAdapter`. */
+  name: string;
+  /** Discriminator for what kind of primitive this is. */
+  kind: IntrospectionKind;
+  /** Optional version string from the plugin / adapter metadata. */
+  version?: string;
+  /**
+   * Reactive state surface — JSON-serialisable snapshot. Keep small
+   * (under a few KB) so polling stays cheap.
+   */
+  state?: Record<string, unknown>;
+  /** DI tokens this primitive registers (`provides`) or consumes (`requires`). */
+  tokens?: {
+    provides: readonly string[];
+    requires: readonly string[];
+  };
+  /**
+   * Per-instance counters — active connections, in-flight jobs, cached
+   * items, etc. Numbers only so the DevTools panel can chart trends.
+   */
+  metrics?: Record<string, number>;
+  /** Self-reported memory footprint estimate, in bytes. Optional. */
+  memoryBytes?: number;
+}
+/**
+ * What kind of primitive an introspection snapshot describes. Matches
+ * the kit's `IntrospectionKind` and the routing the topology aggregator
+ * does when bucketing adapters vs plugins vs middleware vs contributor
+ * primitives.
+ */
+type IntrospectionKind = 'plugin' | 'adapter' | 'middleware' | 'contributor';
+/**
+ * Convenience function signature for adopter-side helpers that return
+ * a complete snapshot. Used by the optional `introspect?()` hook on
+ * `AppAdapter` and `KickPlugin`.
+ */
+type IntrospectFn = () => IntrospectionSnapshot | Promise<IntrospectionSnapshot>;
+//#endregion
+//#region src/core/augmentation.d.ts
+/**
+ * Augmentation registry — runtime no-op + the canonical
+ * `KickJsPluginRegistry` interface that `kick typegen` augments.
+ *
+ * See `architecture.md` §21.2.1 (typegen for `dependsOn`) and §21.3.3
+ * (standardized augmentation registry) for the design rationale.
+ *
+ * @module @forinda/kickjs/core/augmentation
+ */
+/**
+ * Marker interface that lists every plugin/adapter in the project. The
+ * keys are the literal `name` field passed to `defineAdapter` /
+ * `definePlugin` (or declared on a `class implements AppAdapter`); the
+ * values are the kind tag (`'plugin' | 'adapter'`).
+ *
+ * The framework ships this empty. `kick typegen` augments it from
+ * source so `keyof KickJsPluginRegistry` resolves to a string-literal
+ * union of every name in scope — and therefore so do `dependsOn`
+ * declarations on plugins/adapters.
+ */
+interface KickJsPluginRegistry {}
+/**
+ * Resolves to a string-literal union of every registered plugin/adapter
+ * name when the project's typegen has populated `KickJsPluginRegistry`,
+ * or to `string` when the registry is empty (no typegen pass yet).
+ *
+ * Falling back to `string` keeps fresh projects compiling — the typegen
+ * narrowing is a progressive enhancement, not a hard prerequisite.
+ */
+type KickJsPluginName = keyof KickJsPluginRegistry extends never ? string : keyof KickJsPluginRegistry & string;
+/**
+ * Metadata attached to a `defineAugmentation` call. The fields are
+ * documentation-only — `kick typegen` surfaces them in the generated
+ * `.kickjs/types/augmentations.d.ts` so adopters can browse every
+ * augmentable interface from one place.
+ *
+ * `description` and `example` may both be multi-line — typegen preserves
+ * line breaks when rendering them as JSDoc. There is no upper limit on
+ * the example size; entire shape definitions or worked snippets are fine.
+ */
+interface AugmentationMeta {
+  /**
+   * Free-form description of what the augmentation customises. May be
+   * multi-line — newlines are preserved in the generated JSDoc.
+   */
+  description?: string;
+  /**
+   * TS snippet showing a typical shape. May be multi-line; rendered
+   * inside a fenced code block in the generated catalogue. Use this
+   * for anything from `'{ foo: string }'` up to a full interface body
+   * — typegen no longer flattens newlines.
+   */
+  example?: string;
+}
+/**
+ * Advertise an augmentable interface so `kick typegen` can list it in
+ * `.kickjs/types/augmentations.d.ts` for project-wide discovery.
+ *
+ * **This function is a runtime AND type-level no-op.** It does NOT
+ * augment the interface for TypeScript. The actual augmentation is
+ * the `declare module` block — `defineAugmentation` only adds an
+ * entry to the typegen catalogue so other contributors / adopters
+ * can find the interface and know its expected shape.
+ *
+ * Both calls are needed:
+ *
+ * ```ts
+ * import { defineAugmentation } from '@forinda/kickjs'
+ *
+ * // (1) The actual TS augmentation — what `ctx.get('tenant')` reads.
+ * declare module '@forinda/kickjs' {
+ *   interface ContextMeta {
+ *     tenant: { id: string; name: string }
+ *   }
+ * }
+ *
+ * // (2) Catalogue entry — what `kick typegen` lists in
+ * //     `.kickjs/types/augmentations.d.ts` for browseability.
+ * defineAugmentation('ContextMeta', {
+ *   description: 'Tenant resolved from x-tenant-id by TenantAdapter',
+ *   example: `{
+ *     tenant: {
+ *       id: string
+ *       name: string
+ *       plan: 'free' | 'pro' | 'enterprise'
+ *       featureFlags: Record<string, boolean>
+ *     }
+ *   }`,
+ * })
+ * ```
+ *
+ * Skip `defineAugmentation` if you don't care about the catalogue — the
+ * `declare module` block alone is enough for runtime + type behaviour.
+ *
+ * @deprecated Low value in practice: it does nothing at runtime or at
+ * the type level — the `declare module` block alone gives you the
+ * augmentation, and the generated `.kickjs/types/kick__augmentations.d.ts`
+ * catalogue it feeds is documentation-only. Prefer a plain
+ * `declare module '@forinda/kickjs' { ... }` block and (optionally) a
+ * JSDoc comment on your own interface. `defineAugmentation` and the
+ * `kick/augmentations` typegen plugin will be removed in a future major.
+ */
+declare function defineAugmentation(name: string, meta?: AugmentationMeta): void;
+//#endregion
+//#region src/core/module-registry.d.ts
+/**
+ * Imperative receiver passed to {@link KickPlugin.setup} and the
+ * top-level `bootstrap({ setup })` callback so adopters can register
+ * modules conditionally — based on env flags, runtime config,
+ * tenant lists, etc. — instead of being limited to the static
+ * `modules: [...]` array.
+ *
+ * @example
+ * ```ts
+ * bootstrap({
+ *   modules: [HelloModule()],          // static — always mounted
+ *   setup(registry) {
+ *     if (env.ENABLE_ADMIN) registry.mount(AdminModule())
+ *     for (const tenant of env.TENANTS) {
+ *       registry.mount(TenantModule.scoped(tenant.id, { id: tenant.id }))
+ *     }
+ *   },
+ * })
+ * ```
+ *
+ * **Currently exposes only `.mount(module)` — the HTTP-feature path.**
+ * A future `.use(module)` for non-HTTP modules (queues, cron, workers,
+ * DI-only seeds) is planned but not yet implemented; existing non-HTTP
+ * modules continue returning `null` from `routes()` and registering
+ * via `.mount()`.
+ *
+ * Same dispatch rules as the static `modules: [...]` array — class
+ * entries get `new`-ed at boot, `defineModule` factory output is used
+ * directly. The registry doesn't validate the entry shape itself; the
+ * Application loader does the typeof discrimination at mount time.
+ */
+interface ModuleRegistry {
+  /**
+   * Register a module for the full HTTP lifecycle: `register()` runs,
+   * `import.meta.glob` decorator side-effects fire, `routes()` is
+   * called and its result mounted, `contributors()` are merged at
+   * `'module'` precedence and applied to the mounted routes.
+   *
+   * Modules are mounted in registration order (first call → first
+   * mount). Order across sources is: plugin static modules → plugin
+   * `setup()` calls → user static modules → user `setup()` callback.
+   */
+  mount(module: AppModuleEntry): void;
+}
+/**
+ * Internal collector implementing {@link ModuleRegistry}. Application
+ * passes one of these to every `setup()` callback during bootstrap;
+ * the collected `entries` array is then run through the same
+ * class-vs-instance dispatch as the static `modules: [...]` array.
+ *
+ * Not exported from the public surface — adopters interact only
+ * through the {@link ModuleRegistry} interface.
+ */
+declare class MutableModuleRegistry implements ModuleRegistry {
+  readonly entries: AppModuleEntry[];
+  mount(module: AppModuleEntry): void;
+}
+//#endregion
+//#region src/core/plugin.d.ts
+/**
+ * Plugin interface for extending KickJS applications.
+ *
+ * Plugins bundle modules, adapters, middleware, and DI bindings into a single
+ * reusable unit. They run before the application bootstraps, so they can
+ * register services and configure the app before any module loads.
+ *
+ * @example
+ * ```ts
+ * import type { KickPlugin } from '@forinda/kickjs'
+ *
+ * export class CorsPlugin implements KickPlugin {
+ *   name = 'CorsPlugin'
+ *
+ *   middleware() {
+ *     return [cors({ origin: '*' })]
+ *   }
+ * }
+ *
+ * // Usage:
+ * bootstrap({
+ *   modules,
+ *   plugins: [new CorsPlugin()],
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // A more complex plugin that bundles modules and adapters
+ * export class AuthPlugin implements KickPlugin {
+ *   name = 'AuthPlugin'
+ *
+ *   constructor(private config: AuthConfig) {}
+ *
+ *   register(container: Container) {
+ *     container.registerFactory(AUTH_SERVICE, () => new JwtAuthService(this.config))
+ *   }
+ *
+ *   modules() {
+ *     return [AuthModule]
+ *   }
+ *
+ *   adapters() {
+ *     return [new AuthGuardAdapter(this.config)]
+ *   }
+ *
+ *   middleware() {
+ *     return [passport.initialize()]
+ *   }
+ * }
+ * ```
+ */
+interface KickPlugin {
+  /** Human-readable name for logging, debugging, and `dependsOn` resolution. */
+  name: string;
+  /**
+   * Other plugin names that must mount before this one. The framework
+   * topologically sorts plugins at boot — cycles or unknown names throw
+   * via {@link MountCycleError} / {@link MissingMountDepError} so bad
+   * configurations fail boot rather than corrupt live traffic.
+   *
+   * Plugins with no `dependsOn` retain their declaration order, so
+   * existing apps that don't use this field see no behaviour change.
+   *
+   * @example
+   * ```ts
+   * class MonitoringPlugin implements KickPlugin {
+   *   name = 'MonitoringPlugin'
+   *   // OTel must initialize traces before request logger reads them
+   *   dependsOn = ['OtelPlugin']
+   * }
+   * ```
+   */
+  dependsOn?: readonly KickJsPluginName[];
+  /**
+   * Register DI bindings before modules load.
+   * Use this to provide services that modules depend on.
+   */
+  register?(container: Container): void;
+  /**
+   * Return modules to be loaded alongside user modules. Plugin
+   * modules are loaded before user modules.
+   *
+   * Accepts both class form (`SomeModule extends AppModule`) and
+   * instance form (output of {@link defineModule}'s factory call,
+   * e.g. `TasksModule({ scope: 'admin' })`) — the bootstrap loader
+   * discriminates and either `new`-s the class or uses the instance
+   * directly.
+   *
+   * Static path — for conditional / dynamic registration, use
+   * {@link KickPlugin.setup} instead.
+   */
+  modules?(): AppModuleEntry[];
+  /**
+   * Imperative module registration hook. Receives a {@link ModuleRegistry}
+   * the plugin can call `.mount(module)` on to register modules
+   * conditionally — e.g. based on injected config, env flags, or a
+   * tenant list resolved at boot.
+   *
+   * Runs after the static {@link KickPlugin.modules} array is collected
+   * but before user modules and the user-level `setup()` callback. The
+   * plugin sees the same dispatch rules as everything else: class
+   * entries get `new`-ed, factory output is used directly.
+   *
+   * @example
+   * ```ts
+   * definePlugin<{ tenants: string[] }>({
+   *   name: 'MultiTenantPlugin',
+   *   build: (config) => ({
+   *     setup(registry) {
+   *       for (const tenant of config.tenants) {
+   *         registry.mount(TenantModule.scoped(tenant, { id: tenant }))
+   *       }
+   *     },
+   *   }),
+   * })
+   * ```
+   */
+  setup?(registry: ModuleRegistry): void;
+  /**
+   * Return adapter instances to be added to the application.
+   * Plugin adapters are added before user adapters.
+   */
+  adapters?(): AppAdapter[];
+  /**
+   * Return Express middleware to be added to the global pipeline.
+   * Plugin middleware runs before user-defined middleware.
+   */
+  middleware?(): any[];
+  /**
+   * Return Context Contributors (#107) the plugin ships. Contributors
+   * returned here merge into the per-route pipeline at the **`'adapter'`
+   * precedence level** — same as those returned by adapters the plugin
+   * ships via {@link KickPlugin.adapters}, and for the same reason: a
+   * plugin is a cross-cutting bundle, narrower than the global default
+   * but broader than a per-module hook.
+   *
+   * Use when a plugin wants to ship a typed contributor without standing
+   * up an accompanying adapter. For full coverage of the precedence
+   * matrix (method > class > module > adapter > global) see
+   * `docs/guide/context-decorators.md`.
+   *
+   * @example
+   * ```ts
+   * import { defineContextDecorator, type KickPlugin } from '@forinda/kickjs'
+   *
+   * const LoadFlags = defineContextDecorator({
+   *   key: 'flags',
+   *   resolve: (ctx) => fetchFlags(ctx.requestId!),
+   * })
+   *
+   * export class FlagsPlugin implements KickPlugin {
+   *   name = 'FlagsPlugin'
+   *   contributors() {
+   *     return [LoadFlags.registration]
+   *   }
+   * }
+   * ```
+   */
+  contributors?(): ContributorRegistrations;
+  /**
+   * Called after the application has fully bootstrapped.
+   * Use for post-startup logic like logging, health registration, etc.
+   */
+  onReady?(container: Container): void | Promise<void>;
+  /**
+   * Called during application shutdown.
+   * Clean up plugin resources (connections, intervals, etc.).
+   */
+  shutdown?(): void | Promise<void>;
+  /**
+   * Optional DevTools introspection hook (architecture.md §23). Returns
+   * a snapshot describing this plugin's current state, metrics, and DI
+   * tokens. DevTools awaits the result, so async work is fine — but keep
+   * the implementation cheap (counters + flags, no DB round trips) since
+   * the topology endpoint polls on a short interval.
+   *
+   * The return type lives in `@forinda/kickjs` itself
+   * ({@link IntrospectionSnapshot}) so adopters can author `introspect()`
+   * without importing the kit just to satisfy the contract. The kit's
+   * own `IntrospectionSnapshot` type stays structurally identical;
+   * either import works.
+   */
+  introspect?(): IntrospectionSnapshot | Promise<IntrospectionSnapshot>;
+  /**
+   * Optional DevTools tabs this plugin contributes (architecture.md §23).
+   * Same shape as {@link AppAdapter.devtoolsTabs}; the kit's
+   * `DevtoolsTabDescriptor` types it for plugin authors.
+   */
+  devtoolsTabs?(): readonly unknown[];
+}
+//#endregion
+//#region src/core/define-plugin.d.ts
+/**
+ * Options passed to {@link definePlugin}. Mirrors the spec in
+ * `architecture.md` §21.3.1 + §21.2.2 (Phase A "lite").
+ */
+interface DefinePluginOptions<TConfig> {
+  /** Stable identity used for logging, `dependsOn` lookups, and `.scoped()` namespacing. */
+  name: string;
+  /** Optional plugin version — surfaced to DevTools and `kick add` compatibility checks (Phase B). */
+  version?: string;
+  /**
+   * Peer-version ranges this plugin needs from the framework or other
+   * plugins. Recorded as metadata; runtime enforcement lands in §21.4.4.
+   */
+  requires?: {
+    kickjs?: string;
+  };
+  /** Default config merged under any caller overrides. */
+  defaults?: Partial<TConfig>;
+  /** Builds the underlying {@link KickPlugin} from the resolved config. */
+  build(config: TConfig, ctx: BuildContext): Omit<KickPlugin, 'name'>;
+}
+/**
+ * Hook context handed to a plugin/adapter `build` function. `name` is the
+ * resolved instance name (the bare definition name for the bare call,
+ * or `${defName}:${scope}` for `.scoped()`). `scoped` is the discriminator
+ * authors use to namespace DI tokens or resource keys.
+ */
+interface BuildContext {
+  name: string;
+  scoped: boolean;
+}
+/**
+ * Async-config form of a plugin or adapter — `inject` lists DI tokens to
+ * resolve from the container, then `useFactory` produces the config.
+ *
+ * Plugins resolve this lazily inside `onReady`, so any module/adapter/
+ * middleware/contributor a plugin contributes via `build` is **not
+ * available** when `.async()` is used. Use the bare/`.scoped()` form for
+ * plugins that need to register modules or middleware.
+ */
+interface PluginAsyncOptions<TConfig> {
+  inject?: ReadonlyArray<unknown>;
+  useFactory(...deps: any[]): TConfig | Promise<TConfig>;
+}
+/**
+ * Factory returned by {@link definePlugin}. Callable form is the singleton
+ * (`AuthPlugin(config)`); `.scoped()` and `.async()` are the multi-instance
+ * and deferred-config forms.
+ */
+interface PluginFactory<TConfig> {
+  (config?: Partial<TConfig>): KickPlugin;
+  scoped(scopeName: string, config?: Partial<TConfig>): KickPlugin;
+  async(opts: PluginAsyncOptions<TConfig>): KickPlugin;
+  /** Read-only access to the original definition — useful for DevTools introspection. */
+  readonly definition: Readonly<DefinePluginOptions<TConfig>>;
+}
+/**
+ * Build a {@link KickPlugin} factory from a typed definition. See
+ * `architecture.md` §21.2.2 for the design rationale.
+ *
+ * @example
+ * ```ts
+ * const FlagsPlugin = definePlugin<FlagsConfig>({
+ *   name: 'FlagsPlugin',
+ *   defaults: { defaultTtl: 60_000 },
+ *   build(config) {
+ *     return {
+ *       register(container) {
+ *         container.registerInstance(FLAGS, makeProvider(config))
+ *       },
+ *     }
+ *   },
+ * })
+ *
+ * bootstrap({ plugins: [FlagsPlugin({ provider: launchDarkly })] })
+ * ```
+ */
+declare function definePlugin<TConfig = Record<string, unknown>>(options: DefinePluginOptions<TConfig>): PluginFactory<TConfig>;
+//#endregion
+//#region src/core/define-module.d.ts
+/**
+ * Options passed to {@link defineModule}. Mirrors {@link DefineAdapterOptions}
+ * and {@link DefinePluginOptions} so adopters learn one mental model
+ * across all three primitives.
+ *
+ * The optional `TExtra` generic lets a module ship public methods
+ * beyond the standard {@link AppModule} contract — they're preserved
+ * on the returned module instance so external callers (tests, sibling
+ * modules) can invoke them directly.
+ */
+interface DefineModuleOptions<TConfig, TExtra = unknown> {
+  /**
+   * Stable identity surfaced in diagnostics, route logs, and
+   * `.scoped()` namespacing. Required because boot-time error
+   * messages reference modules by name — anonymous modules make
+   * cycles + missing-dep errors hard to localize.
+   */
+  name: string;
+  /** Optional version string surfaced in diagnostics. */
+  version?: string;
+  /**
+   * Optional kickjs version constraint. Enforced by the framework
+   * when implemented; today it lives on the definition for
+   * documentation and forward compatibility.
+   */
+  requires?: {
+    kickjs?: string;
+  };
+  /**
+   * Default config merged with overrides at instantiation time
+   * (`MyModule({ field: x })`). Call-site overrides win.
+   */
+  defaults?: Partial<TConfig>;
+  /**
+   * Build the AppModule shape from the resolved config and context.
+   * `ctx.name` is the resolved instance name (the bare definition
+   * name for the default call, or `${name}:${scope}` for
+   * `.scoped()`); `ctx.scoped` discriminates so the build function
+   * can branch on namespacing if needed.
+   *
+   * Return any extension methods alongside the standard
+   * {@link AppModule} surface — they're typed via `TExtra` and stay
+   * accessible on the resulting instance.
+   */
+  build(config: TConfig, ctx: BuildContext): AppModule & TExtra;
+}
+/**
+ * Factory returned by {@link defineModule}. Mirrors {@link AdapterFactory}
+ * — call (`MyModule({...})`), scope (`MyModule.scoped('public', {...})`),
+ * inspect (`MyModule.definition`).
+ *
+ * `.async()` is intentionally **not** part of the module factory
+ * surface. Module config has no async-resolution window: `register()`
+ * and `routes()` both run synchronously during bootstrap, before any
+ * adapter `beforeStart` hook fires. Adopters that need async-resolved
+ * config push it into an adapter (which has `beforeStart`), then
+ * inject the resolved value into the module via DI tokens.
+ */
+interface ModuleFactory<TConfig, TExtra = unknown> {
+  (config?: Partial<TConfig>): AppModule & TExtra;
+  scoped(scopeName: string, config?: Partial<TConfig>): AppModule & TExtra;
+  readonly definition: Readonly<DefineModuleOptions<TConfig, TExtra>>;
+}
+/**
+ * Build an {@link AppModule} factory from a typed definition. Pairs
+ * with {@link defineAdapter}, {@link definePlugin}, and
+ * {@link defineContextDecorator} as the fourth `define*` primitive
+ * — adopters write modules the same way they write adapters and
+ * plugins.
+ *
+ * The returned factory produces real {@link AppModule} instances
+ * that drop into `bootstrap({ modules })` directly. The legacy
+ * class form (`class TasksModule implements AppModule { ... }`) keeps
+ * working — `bootstrap` accepts either shape.
+ *
+ * @example
+ * ```ts
+ * interface TasksConfig {
+ *   scope: 'public' | 'admin'
+ * }
+ *
+ * const TasksModule = defineModule<TasksConfig>({
+ *   name: 'TasksModule',
+ *   defaults: { scope: 'public' },
+ *   build: (config, { name }) => ({
+ *     register(container) {
+ *       container.registerInstance(`tasks:scope:${name}`, config.scope)
+ *     },
+ *     routes() {
+ *       return { path: `/${config.scope}/tasks`, router: buildTasksRouter() }
+ *     },
+ *     contributors() {
+ *       return [LoadTenant.registration]
+ *     },
+ *   }),
+ * })
+ *
+ * bootstrap({
+ *   modules: [
+ *     TasksModule(),                              // public scope (defaults)
+ *     TasksModule.scoped('admin', { scope: 'admin' }),
+ *   ],
+ * })
+ * ```
+ */
+declare function defineModule<TConfig = Record<string, unknown>, TExtra = unknown>(options: DefineModuleOptions<TConfig, TExtra>): ModuleFactory<TConfig, TExtra>;
+//#endregion
+//#region src/core/define-modules.d.ts
+/**
+ * Chainable registry returned by {@link defineModules}. Extends
+ * `Array<AppModuleEntry>` so it drops into `bootstrap({ modules })`
+ * unchanged — the framework loader already iterates the array, so a
+ * `ModuleList` IS a valid `modules` value with no special handling.
+ *
+ * The added affordance is `.mount(module)` returning `this` so
+ * adopters can build the list fluently:
+ *
+ * ```ts
+ * const modules = defineModules()
+ *   .mount(HelloModule())
+ *   .mount(AdminModule())
+ *
+ * bootstrap({ modules })
+ * ```
+ *
+ * **Why not just use a plain array?** Two reasons. First, the
+ * fluent shape reads more naturally for module-list construction —
+ * adopters used to `definePlugin().scoped(...)` / `defineAdapter(...)`
+ * see the same call-then-call pattern. Second, the registry is the
+ * stable extension point: a future `.use(module)` for non-HTTP
+ * modules (queues, cron, workers) lands as a method on `ModuleList`
+ * without breaking the `Array<AppModuleEntry>` superclass contract.
+ */
+declare class ModuleList extends Array<AppModuleEntry> {
+  /**
+   * Append a module to the list. Returns `this` for chaining.
+   *
+   * Accepts both class form (`SomeModule extends AppModule`) and
+   * `defineModule` factory output — same as the underlying
+   * `bootstrap({ modules })` array. The framework loader
+   * discriminates `typeof entry === 'function'` at boot.
+   */
+  mount(module: AppModuleEntry): this;
+}
+/**
+ * Build a {@link ModuleList} for the application. Optional vararg
+ * lets adopters seed the list inline; subsequent `.mount()` calls
+ * append.
+ *
+ * @example
+ * ```ts
+ * import { bootstrap, defineModules } from '@forinda/kickjs'
+ * import { HelloModule } from './modules/hello/hello.module'
+ * import { AdminModule } from './modules/admin/admin.module'
+ *
+ * // Fluent — most common
+ * const modules = defineModules()
+ *   .mount(HelloModule())
+ *   .mount(AdminModule())
+ *
+ * // Or seeded inline + chained
+ * const modules2 = defineModules(HelloModule()).mount(AdminModule())
+ *
+ * await bootstrap({ modules })
+ * ```
+ *
+ * The returned value is an `AppModuleEntry[]` subclass — `bootstrap`
+ * accepts it directly without any special-casing. For conditional /
+ * dynamic registration at bootstrap time (env flags, runtime config,
+ * tenant lists), use the `setup(registry)` callback on `bootstrap`
+ * instead — both surfaces compose.
+ */
+declare function defineModules(...initial: AppModuleEntry[]): ModuleList;
+//#endregion
+//#region src/core/kick-error.d.ts
+/**
+ * Structured framework error with code, cause, and actionable fix hint.
+ *
+ * The goal is "the developer who hits this knows what to do next." A
+ * cryptic `Error('No binding found for: UserService')` becomes a
+ * multi-line explanation pointing at the likely cause, the exact code
+ * change to apply, and a docs link.
+ *
+ * `.message` carries the full multi-line plain-text body so Node's
+ * default `Error.toString()` and unhandled-exception printing still
+ * surface the helpful version. Call {@link formatKickError} to render a
+ * colorized version for terminals.
+ *
+ * Per-error factories live in `kick-errors.ts` — those are the public
+ * entry points framework code uses. `KickError` is exported so adopters
+ * can build their own structured errors using the same shape.
+ */
+interface KickErrorInit {
+  /** Short stable identifier (e.g. `KICK001`, `NO_PROVIDER`). */
+  code: string;
+  /** One-line headline. */
+  summary: string;
+  /** Multi-line explanation of why this happened. */
+  cause?: string;
+  /** Multi-line actionable fix — show exact code if possible. */
+  fix?: string;
+  /** Absolute URL to the docs page that covers this error. */
+  docsUrl?: string;
+  /** Arbitrary structured fields for log consumers / debug tooling. */
+  context?: Record<string, unknown>;
+}
+declare class KickError extends Error {
+  readonly code: string;
+  readonly summary: string;
+  readonly cause?: string;
+  readonly fix?: string;
+  readonly docsUrl?: string;
+  readonly context?: Record<string, unknown>;
+  constructor(init: KickErrorInit);
+}
+interface FormatKickErrorOptions {
+  /**
+   * Render ANSI colour codes. Defaults to TTY detection (`NO_COLOR` /
+   * `FORCE_COLOR` env vars honoured). Pass `false` for log files,
+   * structured loggers, or HTTP response bodies.
+   */
+  color?: boolean;
+}
+/**
+ * Render a {@link KickErrorInit} (or {@link KickError} instance) into a
+ * multi-line human-readable string. Identical layout regardless of
+ * colour — the colour flag only toggles ANSI codes.
+ */
+declare function formatKickError(err: KickErrorInit | KickError, options?: FormatKickErrorOptions): string;
+//#endregion
+//#region src/core/metadata.d.ts
+/**
+ * Typed utilities for reflect-metadata operations.
+ *
+ * Replaces scattered Reflect.defineMetadata/getMetadata calls with a single
+ * source of truth. If we later move to Stage 3 decorators or a WeakMap-based
+ * store, only this file changes — all 24+ consumer files stay untouched.
+ *
+ * Keys may be symbols, strings, or `InjectionToken<T>` objects produced by
+ * `createToken()`. Using `createToken` is the preferred pattern because the
+ * token's phantom type flows through the helpers, enabling type-safe reads.
+ */
+type MetaKey = symbol | string | InjectionToken<unknown>;
+/** Set metadata on a class (or prototype for property decorators) */
+declare function setClassMeta<T>(key: MetaKey, value: T, target: object): void;
+/** Set metadata on a specific method */
+declare function setMethodMeta<T>(key: MetaKey, value: T, target: object, method: string): void;
+/** Get metadata from a class, returning `fallback` if not set */
+declare function getClassMeta<T>(key: MetaKey, target: object, fallback: T): T;
+/** Get metadata from a specific method, returning `fallback` if not set */
+declare function getMethodMeta<T>(key: MetaKey, target: object, method: string, fallback: T): T;
+/** Check if metadata exists on a class */
+declare function hasClassMeta(key: MetaKey, target: object): boolean;
+/** Get metadata from a class with no default (returns undefined if absent) */
+declare function getClassMetaOrUndefined<T>(key: MetaKey, target: object): T | undefined;
+/** Get metadata from a method with no default (returns undefined if absent) */
+declare function getMethodMetaOrUndefined<T>(key: MetaKey, target: object, method: string): T | undefined;
+/** Append items to an array stored in class metadata */
+declare function pushClassMeta<T>(key: MetaKey, target: object, ...items: T[]): void;
+/** Append items to an array stored in method metadata */
+declare function pushMethodMeta<T>(key: MetaKey, target: object, method: string, ...items: T[]): void;
+/** Set a key/value in a Map stored in class metadata */
+declare function setInMetaMap<K, V>(key: MetaKey, target: object, mapKey: K, mapValue: V): void;
+/** Get a Map from class metadata (returns empty Map if absent) */
+declare function getMetaMap<K, V>(key: MetaKey, target: object): Map<K, V>;
+/** Set a key/value in a Record stored in class metadata */
+declare function setInMetaRecord<V>(key: MetaKey, target: object, recKey: string | number, recValue: V): void;
+/** Get a Record from class metadata (returns empty object if absent) */
+declare function getMetaRecord<V>(key: MetaKey, target: object): Record<string | number, V>;
+//#endregion
+//#region src/core/circuit-breaker.d.ts
+/**
+ * Circuit Breaker pattern for external service calls.
+ *
+ * Protects your application from cascading failures when downstream
+ * services are unhealthy by short-circuiting requests after a
+ * configurable failure threshold.
+ *
+ * @example
+ * ```ts
+ * const breaker = new CircuitBreaker('payment-api', {
+ *   failureThreshold: 5,
+ *   resetTimeout: 30_000,
+ * })
+ *
+ * const result = await breaker.execute(() => fetch('https://payment.example.com/charge'))
+ * ```
+ */
+type CircuitBreakerState = 'closed' | 'open' | 'half_open';
+interface CircuitBreakerOptions {
+  /** Number of consecutive failures before the circuit opens. */
+  failureThreshold: number;
+  /** Milliseconds to wait before transitioning from OPEN to HALF_OPEN. */
+  resetTimeout: number;
+  /** Max requests allowed in HALF_OPEN state before deciding (default 1). */
+  halfOpenMax?: number;
+}
+interface CircuitBreakerStats {
+  failures: number;
+  successes: number;
+  state: CircuitBreakerState;
+  lastFailure?: Date;
+}
+/**
+ * Error thrown when the circuit is open and calls are being rejected.
+ */
+declare class CircuitOpenError extends Error {
+  readonly breakerName: string;
+  constructor(breakerName: string);
+}
+declare class CircuitBreaker {
+  readonly name: string;
+  private state;
+  private failures;
+  private successes;
+  private halfOpenAttempts;
+  private lastFailure?;
+  private openedAt?;
+  private readonly failureThreshold;
+  private readonly resetTimeout;
+  private readonly halfOpenMax;
+  constructor(name: string, options: CircuitBreakerOptions);
+  /**
+   * Execute an async function through the circuit breaker.
+   * Throws `CircuitOpenError` if the circuit is open.
+   */
+  execute<T>(fn: () => Promise<T>): Promise<T>;
+  /** Returns the current circuit state. */
+  getState(): CircuitBreakerState;
+  /** Returns current statistics. */
+  getStats(): CircuitBreakerStats;
+  /** Manually reset the circuit breaker to CLOSED state. */
+  reset(): void;
+  private onSuccess;
+  private onFailure;
+  private maybeTransitionToHalfOpen;
+}
+//#endregion
+//#region src/core/context-errors.d.ts
+/**
+ * Errors thrown by the Context Contributor pipeline.
+ *
+ * All three are startup-time errors raised during pipeline build (topo-sort
+ * + validation), not per-request — a misconfigured app fails to boot rather
+ * than fails a request. Per the locked design in `architecture.md` §20.4,
+ * the pipeline is validated once when each route is mounted and the
+ * resolved order is cached on the route.
+ */
+/**
+ * A contributor declared `dependsOn: ['<key>']` but no other contributor
+ * (at any precedence level) produces that key for the same route.
+ *
+ * @example
+ * ```text
+ * MissingContributorError: Missing context contributor 'tenant' required by 'project' on route GET /projects/:id
+ *     declared at src/contributors/load-project.ts:42:18
+ * ```
+ */
+declare class MissingContributorError extends Error {
+  readonly key: string;
+  readonly dependent: string;
+  readonly route?: string;
+  readonly dependentDefinedAt?: string;
+  constructor(key: string, dependent: string, route?: string, dependentDefinedAt?: string);
+}
+/**
+ * Topo-sort detected a cycle in `dependsOn` declarations. The `cycle` field
+ * lists the keys in the order they form the loop, with the first key
+ * repeated at the end so the path reads naturally.
+ *
+ * @example
+ * ```text
+ * ContributorCycleError: Cycle in context contributors on route GET /projects/:id: tenant → project → tenant
+ * ```
+ */
+declare class ContributorCycleError extends Error {
+  readonly cycle: readonly string[];
+  readonly route?: string;
+  constructor(cycle: readonly string[], route?: string);
+}
+/**
+ * Two contributors at the same precedence level both produce the same key
+ * for the same route. Precedence resolution (method > class > module >
+ * adapter > global, per architecture.md §20.4) silently drops
+ * lower-precedence duplicates; this error fires only when ties occur
+ * within a single level — e.g., two method-level decorators declaring
+ * `key: 'tenant'`.
+ *
+ * `sources` is best-effort identifying labels for each conflicting
+ * registration (typically the decorator's call site or registering
+ * module/adapter name).
+ *
+ * @example
+ * ```text
+ * DuplicateContributorError: Duplicate context contributor for key 'tenant' at the same precedence level. Sources: LoadTenantFromHeader, LoadTenantFromSubdomain
+ * ```
+ */
+declare class DuplicateContributorError extends Error {
+  readonly key: string;
+  readonly sources: readonly string[];
+  constructor(key: string, sources: readonly string[]);
+}
+//#endregion
+//#region src/core/contributor-pipeline.d.ts
+/**
+ * Where a contributor was registered, ordered by precedence
+ * (lower index wins). Mirrors `architecture.md` §20.4.
+ *
+ * Levels (highest → lowest precedence):
+ * - `'method'` — `@LoadX` on a controller method.
+ * - `'class'`  — `@LoadX` on a controller class.
+ * - `'module'` — returned by `AppModule.contributors?()`. Per-module scope.
+ * - `'adapter'` — returned by `AppAdapter.contributors?()`. Cross-cutting, applies
+ *   to every module's routes.
+ * - `'global'` — `ApplicationOptions.contributors`. App-wide default.
+ */
+type ContributorSource = 'method' | 'class' | 'module' | 'adapter' | 'global';
+/**
+ * Input row to {@link buildPipeline}. Pairs a registration with its origin
+ * so dedup can apply the precedence rule and diagnostic errors can name
+ * the offending site.
+ *
+ * `registration` is the type-erased {@link AnyContributorRegistration}
+ * — the runner doesn't care about each registration's narrow `D` /
+ * `Ctx` shape, and adopters frequently mix HTTP / transport-agnostic
+ * contributors in the same `externalSources` / `contributors()`
+ * array. The narrow generics from `defineContextDecorator` survive
+ * at the *definition* site (where `resolve` is typed); they're erased
+ * here so collections compose without `as any` casts.
+ */
+interface SourcedRegistration {
+  registration: AnyContributorRegistration;
+  source: ContributorSource;
+  /** Human label surfaced in DuplicateContributorError messages. */
+  label?: string;
+}
+/**
+ * Resolved, validated, topo-sorted pipeline ready for execution.
+ *
+ * `contributors` is in execution order — every entry's `dependsOn`
+ * keys appear earlier. `keys` is the set of all keys this pipeline
+ * produces; the runner uses it for fast existence checks and the
+ * builder uses it for missing-dep validation.
+ */
+interface ContributorPipeline {
+  readonly contributors: readonly AnyContributorRegistration[];
+  readonly keys: ReadonlySet<string>;
+}
+interface BuildPipelineOptions {
+  /** Optional route identifier surfaced in diagnostic errors (e.g., 'GET /projects/:id'). */
+  route?: string;
+}
+/**
+ * Build, validate, and topo-sort a contributor pipeline.
+ *
+ * Pipeline:
+ *
+ * 1. Group sources by precedence (method > class > module > adapter > global).
+ * 2. Within each precedence level, two contributors with the same `key`
+ *    raise {@link DuplicateContributorError}.
+ * 3. Across levels, the highest-precedence contributor wins each key
+ *    (lower-precedence duplicates are silently dropped — that is the
+ *    documented override mechanism, not an error).
+ * 4. Every key referenced by `dependsOn` must be produced by the
+ *    surviving set, otherwise {@link MissingContributorError}.
+ * 5. Kahn's algorithm topo-sorts the survivors. Any nodes left after
+ *    the queue drains form a cycle → {@link ContributorCycleError}
+ *    with a reconstructed path.
+ *
+ * Pure function — no DI, no I/O. Safe to call once at startup per
+ * route and cache the result.
+ */
+declare function buildPipeline(sources: readonly SourcedRegistration[], options?: BuildPipelineOptions): ContributorPipeline;
+//#endregion
+//#region src/core/contributor-runner.d.ts
+interface RunContributorsOptions {
+  /** Pre-built, validated, topo-sorted pipeline. */
+  pipeline: ContributorPipeline;
+  /** The execution context contributors read from and write into. */
+  ctx: ExecutionContext;
+  /** DI container used to resolve declared `deps`. */
+  container: Container;
+}
+/**
+ * Execute a built {@link ContributorPipeline} against an {@link ExecutionContext}.
+ *
+ * Sequential — one contributor at a time, in the topo order chosen at
+ * pipeline-build time. Per `architecture.md` §20.10, V1 does not run
+ * contributors in parallel even within the same topo level; that is a
+ * V2 follow-up gated on profiling.
+ *
+ * ## Error matrix (architecture.md §20.9)
+ *
+ * | resolve outcome | optional | onError defined | runner behaviour                                 |
+ * |-----------------|----------|-----------------|--------------------------------------------------|
+ * | throws          | true     | —               | skip; `ctx.get(key)` remains undefined           |
+ * | throws          | false    | yes             | call hook; returned value (if any) stored        |
+ * | throws          | false    | no              | propagate the original error                     |
+ * | hook throws     | —        | yes             | propagate the new error                          |
+ * | hook returns    | —        | yes             | undefined/void → skip; value → `ctx.set(key, v)` |
+ * | resolves        | —        | —               | `ctx.set(key, value)`                            |
+ *
+ * Container.resolve() throwing while building `deps` is treated as a
+ * resolve-side throw and flows through the same matrix — adopters who
+ * need different behaviour for missing-DI vs. data-lookup failures can
+ * wrap the container access inside their own `resolve()`.
+ */
+declare function runContributors(options: RunContributorsOptions): Promise<void>;
+//#endregion
+//#region src/core/mount-sort.d.ts
+/**
+ * Topological sort for plugins and adapters with `dependsOn` declarations.
+ *
+ * Mirrors the algorithm used by the Context Contributor pipeline
+ * (`contributor-pipeline.ts:topoSort`) but operates on a name-keyed
+ * `MountSortItem` shape rather than a `ContributorRegistration`. Kept
+ * standalone instead of factored generic so that:
+ *
+ * 1. The contributor pipeline doesn't need refactoring (risk reduction).
+ * 2. The error classes can carry plugin/adapter-specific diagnostic
+ *    fields (`kind`, `dependent`) without bending the contributor types.
+ */
+/**
+ * A plugin or adapter that participates in dependency-ordered mounting.
+ * Both `KickPlugin` and `AppAdapter` satisfy this shape via their `name`
+ * and `dependsOn` fields.
+ */
+interface MountSortItem {
+  /** Unique mount name within the plugin/adapter set being sorted. */
+  name: string;
+  /**
+   * Other plugin/adapter names that must mount before this one. Cycles
+   * and missing names fail at boot — same fail-fast contract as the
+   * Context Contributor pipeline (architecture.md §20.4).
+   */
+  dependsOn?: readonly string[];
+}
+/** What kind of mount set the sort is operating on — surfaces in error messages. */
+type MountKind = 'plugin' | 'adapter';
+/**
+ * Two items in the same mount set declared the same `name`. Plugin/adapter
+ * names must be unique so `dependsOn` references resolve unambiguously.
+ */
+declare class DuplicateMountNameError extends Error {
+  readonly kind: MountKind;
+  readonly mountName: string;
+  constructor(kind: MountKind, mountName: string);
+}
+/**
+ * A `dependsOn` entry references a plugin/adapter that isn't in the
+ * current set. The dependency might not be installed, might be misspelled,
+ * or might live in a different mount set (plugin referencing an adapter,
+ * or vice versa — they sort independently).
+ */
+declare class MissingMountDepError extends Error {
+  readonly kind: MountKind;
+  readonly missing: string;
+  readonly dependent: string;
+  constructor(kind: MountKind, missing: string, dependent: string);
+}
+/**
+ * The `dependsOn` declarations form a cycle. Boot fails so the cycle
+ * can't poison live traffic. The `cycle` field reports one path through
+ * the offending nodes for diagnostics — formatted `A → B → C → A`.
+ */
+declare class MountCycleError extends Error {
+  readonly kind: MountKind;
+  readonly cycle: readonly string[];
+  constructor(kind: MountKind, cycle: readonly string[]);
+}
+/**
+ * Topologically sort `items` so every item with `dependsOn: ['X']` mounts
+ * after `X`. Items without `dependsOn` keep their input order via Kahn's
+ * algorithm with a FIFO queue seeded in input order — preserves the
+ * historical "plugins/adapters mount in declaration order" behaviour for
+ * any set that doesn't use `dependsOn`.
+ *
+ * @param items - mountable items, e.g. plugins or adapters
+ * @param kind - 'plugin' | 'adapter', used in error messages
+ * @returns a new array in valid mount order
+ * @throws {DuplicateMountNameError} two items share a name
+ * @throws {MissingMountDepError} a `dependsOn` references an unknown name
+ * @throws {MountCycleError} the dep graph contains a cycle
+ */
+declare function mountSort<T extends MountSortItem>(items: readonly T[], kind: MountKind): T[];
+//#endregion
+//#region src/core/define-adapter.d.ts
+/**
+ * Options passed to {@link defineAdapter}. Mirrors {@link DefinePluginOptions}
+ * exactly — see `architecture.md` §21.3.4 for the definePlugin/defineAdapter
+ * symmetry rationale.
+ *
+ * The optional `TExtra` generic lets an adapter ship public methods
+ * beyond the standard {@link AppAdapter} contract — they're preserved
+ * on the returned adapter instance so external callers (tests, peer
+ * adapters) can invoke them directly. See `OtelAdapter.applyRedaction`
+ * for the canonical use case.
+ */
+interface DefineAdapterOptions<TConfig, TExtra = unknown> {
+  /**
+   * Stable identity used for logging, `dependsOn` lookups, and `.scoped()`
+   * namespacing. Required for adapters that participate in `dependsOn`
+   * sort — error messages reference adapters by name.
+   */
+  name: string;
+  version?: string;
+  requires?: {
+    kickjs?: string;
+  };
+  defaults?: Partial<TConfig>;
+  build(config: TConfig, ctx: BuildContext): Omit<AppAdapter, 'name'> & TExtra;
+}
+/**
+ * Async-config form of an adapter. Identical shape to `PluginAsyncOptions`
+ * but resolved during `beforeStart` (the earliest async hook in
+ * `AppAdapter`) — meaning `middleware()` and `contributors()` from the inner
+ * adapter are **not** picked up. Use the bare/`.scoped()` form when you need
+ * those.
+ */
+interface AdapterAsyncOptions<TConfig> {
+  inject?: ReadonlyArray<unknown>;
+  useFactory(...deps: any[]): TConfig | Promise<TConfig>;
+}
+/**
+ * Factory returned by {@link defineAdapter}. Same surface as
+ * {@link PluginFactory} (call / `.scoped()` / `.async()`) so adopters learn
+ * one mental model for both primitives. Returned instances carry both
+ * the standard {@link AppAdapter} contract and any `TExtra` extension
+ * methods the `build` function exposed.
+ */
+interface AdapterFactory<TConfig, TExtra = unknown> {
+  (config?: Partial<TConfig>): AppAdapter & TExtra;
+  scoped(scopeName: string, config?: Partial<TConfig>): AppAdapter & TExtra;
+  async(opts: AdapterAsyncOptions<TConfig>): AppAdapter;
+  readonly definition: Readonly<DefineAdapterOptions<TConfig, TExtra>>;
+}
+/**
+ * Build an {@link AppAdapter} factory from a typed definition. See
+ * `architecture.md` §21.3.4 for migration guidance — most first-party
+ * adapter packages collapse to a single `defineAdapter()` call after this
+ * lands.
+ *
+ * @example
+ * ```ts
+ * const TenantAdapter = defineAdapter<TenantConfig>({
+ *   name: 'TenantAdapter',
+ *   defaults: { strategy: 'header', required: true },
+ *   build: (config) => ({
+ *     middleware: () => [tenantResolverMiddleware(config)],
+ *     beforeStart: ({ container }) => registerTenantFactory(container, config),
+ *   }),
+ * })
+ *
+ * bootstrap({
+ *   adapters: [
+ *     TenantAdapter({ strategy: 'subdomain' }),
+ *     TenantAdapter.scoped('shard-eu', { headerName: 'x-eu-tenant' }),
+ *   ],
+ * })
+ * ```
+ */
+declare function defineAdapter<TConfig = Record<string, unknown>, TExtra = unknown>(options: DefineAdapterOptions<TConfig, TExtra>): AdapterFactory<TConfig, TExtra>;
+//#endregion
+//#region src/core/asset-keys.d.ts
+type AssetKeyStrategy = 'auto' | 'strip' | 'with-extension';
+interface AssetKeyPair {
+  /** Source-relative path the file was discovered at. */
+  rel: string;
+  /** Final logical key for the manifest, including the namespace prefix. */
+  key: string;
+}
+interface GroupAssetKeysOptions {
+  /**
+   * Strategy applied to this namespace. Default `'auto'`.
+   *
+   * Adopters override per-namespace via `assetMap.<ns>.keys` in
+   * kick.config.ts when they want uniform behaviour (e.g. always
+   * include the extension regardless of collisions).
+   */
+  strategy?: AssetKeyStrategy;
+}
+interface GroupAssetKeysResult {
+  pairs: AssetKeyPair[];
+  /**
+   * Number of collision groups resolved by keeping extensions.
+   * Surfaces as an informational log ("auto-resolved N collisions")
+   * so adopters know whether they're relying on auto-mode or not.
+   * Always 0 for `'strip'` (overwrites) and `'with-extension'`
+   * (extensions always preserved, no collision possible).
+   */
+  collisionGroupsResolved: number;
+}
+/**
+ * Compute final manifest keys for a namespace's discovered paths,
+ * given the chosen strategy. Pure function — no fs / config / globals
+ * involved.
+ *
+ * @param namespace assetMap key — e.g. `'mails'`, `'pages'`.
+ * @param paths source-relative file paths (POSIX separators) discovered
+ *              under the namespace's `src` directory.
+ * @param opts grouping options.
+ */
+declare function groupAssetKeys(namespace: string, paths: readonly string[], opts?: GroupAssetKeysOptions): GroupAssetKeysResult;
+/** Strip the final extension from a path. `'mails/welcome.ejs'` → `'mails/welcome'`. */
+declare function stripExt(path: string): string;
+//#endregion
+//#region src/http/context.d.ts
+/**
+ * Input shape for the typed problem-detail convenience methods on
+ * {@link ProblemSender} (`ctx.problem.notFound`, `.badRequest`, etc.) —
+ * RFC 9457 details minus the `status`, which each method pre-fills.
+ */
+type ProblemInput = Omit<ProblemDetails, 'status'>;
+/**
+ * Callable response helper for RFC 9457 — Problem Details responses.
+ * Returned by `ctx.problem`. Invoke directly for a fully-specified
+ * payload, or use the named convenience methods to pre-fill `status` +
+ * `title` for the common codes.
+ *
+ * Each call sets `Content-Type: application/problem+json` and serializes
+ * the canonical shape (defaulting `type` to `about:blank` and `title` to
+ * the IANA reason phrase per RFC 9457 §3.1.1 / §3.1.4).
+ *
+ * @example
+ * ```ts
+ * ctx.problem({
+ *   type: 'https://api.example.com/problems/out-of-credit',
+ *   status: 403,
+ *   detail: 'Your balance is 30, but that costs 50.',
+ *   balance: 30,                // extension per §3.2
+ * })
+ *
+ * ctx.problem.notFound({ detail: 'User abc not found' })
+ * ctx.problem.validation(zodResult.error.issues)
+ * ```
+ */
+interface ProblemSender {
+  (input: ProblemDetails): RuntimeResponse;
+  /** 400 Bad Request — RFC 9457. */
+  badRequest(input?: ProblemInput): RuntimeResponse;
+  /** 401 Unauthorized — RFC 9457. */
+  unauthorized(input?: ProblemInput): RuntimeResponse;
+  /** 403 Forbidden — RFC 9457. */
+  forbidden(input?: ProblemInput): RuntimeResponse;
+  /** 404 Not Found — RFC 9457. */
+  notFound(input?: ProblemInput): RuntimeResponse;
+  /** 409 Conflict — RFC 9457. */
+  conflict(input?: ProblemInput): RuntimeResponse;
+  /** 422 Unprocessable Entity — RFC 9457. */
+  unprocessable(input?: ProblemInput): RuntimeResponse;
+  /** 429 Too Many Requests — RFC 9457. */
+  tooManyRequests(input?: ProblemInput): RuntimeResponse;
+  /** 500 Internal Server Error — RFC 9457. */
+  internal(input?: ProblemInput): RuntimeResponse;
+  /**
+   * 422 with Zod issues serialized into the `errors` extension per
+   * RFC 9457 §3.2's array convention. Pass `error.issues` from a Zod
+   * `safeParse` failure or `error.issues` from a thrown ZodError.
+   */
+  validation(issues: any[], input?: ProblemInput): RuntimeResponse;
+}
+/**
+ * Recursively marks every property of `T` as `readonly`. Preserves
+ * `Function`, `Date`, and `RegExp` unchanged, and converts `Map` / `Set`
+ * to `ReadonlyMap` / `ReadonlySet` so their mutating methods (`set`,
+ * `delete`, `add`, `clear`) are removed from the public surface.
+ * Tuples keep their positional element types — only their per-element
+ * mutability is locked.
+ *
+ * Exposed as a utility for adopters who want to opt into compile-time
+ * sealing of their own shapes. **No longer applied to
+ * `RequestContext.{body,params,query,headers,file,files}`** — that
+ * broke TS narrowing / discriminated-union drilldowns on typed request
+ * payloads. Runtime read-only enforcement now lives in
+ * {@link makeReadOnlyProxy} (dev-only Proxy that warns on writes,
+ * no-op in production).
+ *
+ * Type-only. No runtime cost. `DeepReadonly<any>` is `any` (TS
+ * distributes conditional types over `any`).
+ */
+type DeepReadonly<T> = T extends ((...args: never[]) => unknown) ? T : T extends Date | RegExp ? T : T extends Map<infer K, infer V> ? ReadonlyMap<DeepReadonly<K>, DeepReadonly<V>> : T extends Set<infer V> ? ReadonlySet<DeepReadonly<V>> : T extends readonly (infer U)[] ? number extends T['length'] ? ReadonlyArray<DeepReadonly<U>> : { readonly [K in keyof T]: DeepReadonly<T[K]> } : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> } : T;
+/**
+ * The shape of a single route entry in `KickRoutes`. Generated by
+ * `kick typegen` and consumed via the `Ctx<T>` helper. Each field is
+ * `unknown` by default and is filled in as the typegen learns more
+ * about the route (URL params from the path, body/query from validation
+ * schemas, etc.).
+ */
+interface RouteShape {
+  params?: unknown;
+  body?: unknown;
+  query?: unknown;
+  response?: unknown;
+}
+/**
+ * Unified request/response abstraction passed to every controller method.
+ * Shields handlers from raw Express objects and provides convenience methods.
+ *
+ * Implements {@link ExecutionContext} so the transport-agnostic Context
+ * Contributor pipeline (#107) can run against this concrete HTTP context
+ * the same way it will run against future WS / queue / cron contexts.
+ */
+declare class RequestContext<TBody = any, TParams = any, TQuery = any> implements ExecutionContext {
+  readonly req: ActiveRuntime['request'];
+  readonly res: ActiveRuntime['response'];
+  readonly next: NextFunction;
+  /**
+   * Engine-agnostic response driver the response helpers write through. Under
+   * the Express runtime it IS `res` (Express's Response satisfies
+   * {@link RuntimeResponse} structurally); other runtimes pass a thin wrapper
+   * over their native reply as the optional fourth argument.
+   */
+  private readonly _response;
+  constructor(req: ActiveRuntime['request'], res: ActiveRuntime['response'], next: NextFunction, responseDriver?: RuntimeResponse);
+  /**
+   * Memo of the most recent {@link qs} call this request. The query
+   * object is immutable for a request's lifetime, so a repeat call with
+   * the same `(fieldConfig, options)` references returns the cached
+   * parse instead of re-walking the filter/sort strings.
+   */
+  private _qsMemo?;
+  /**
+   * Read-side accessor for the per-request metadata map.
+   *
+   * Returns the AsyncLocalStorage map (`requestStore.getStore().values`)
+   * shared with the Context Contributor pipeline when an ALS frame is
+   * active. Returns `null` outside any frame — read-side callers
+   * (`ctx.get`, `ctx.user`, `ctx.tenantId`, `ctx.roles`) treat that as
+   * "no metadata" and fall through to their `req.*` defaults. Reads
+   * never throw because outside an ALS frame nobody could have written
+   * via `ctx.set` anyway, so an empty answer is the truthful one.
+   */
+  private metadataReadOnly;
+  /**
+   * Write-side accessor for the per-request metadata map.
+   *
+   * Returns the same map as {@link metadataReadOnly} when an ALS frame
+   * is active. Throws otherwise — writing to a fallback map outside
+   * the ALS frame would silently lose data because other call sites
+   * (downstream contributors, request-logger, etc.) read from the
+   * canonical store and would never see it. Mount
+   * `requestScopeMiddleware()` (Application does this for you in
+   * `'auto'` mode) or wrap your test setup in
+   * `requestStore.run({...}, () => …)` to fix.
+   */
+  private metadataForWrite;
+  /**
+   * Parsed request body. Wrapped in a dev-only Proxy that warns when
+   * adopters try to mutate Zod-validated payloads in place — compute
+   * new values and stash them via `ctx.set('key', value)` or a Context
+   * Contributor instead. Reach for `ctx.req.body` if you genuinely
+   * need the raw, mutable Express handle (rare).
+   *
+   * In production the Proxy is bypassed and `this.req.body` is
+   * returned as-is — no runtime cost on the hot path.
+   */
+  get body(): TBody;
+  /** Path parameters parsed from the route — read-only, see {@link body}. */
+  get params(): TParams;
+  /** Parsed query string — read-only, see {@link body}. */
+  get query(): TQuery;
+  /** Inbound HTTP headers — read-only, see {@link body}. */
+  get headers(): Request['headers'];
+  get requestId(): string | undefined;
+  /**
+   * `AbortSignal` that fires when the underlying HTTP request is
+   * closed — either because the client disconnected before the
+   * response was sent, or because Node's socket-close event ran
+   * after a normal response. Multiple `RequestContext` wrappers for
+   * the same request (router-builder constructs one per
+   * middleware/contributor pipeline / main handler) share a single
+   * `AbortController` cached on the underlying `req` object, so the
+   * signal is stable across the request lifecycle.
+   *
+   * Thread it through anything that takes an `AbortSignal` so the
+   * work cancels as soon as the client gives up — e.g. a kickjs-db
+   * relational query:
+   *
+   * ```ts
+   * @Get('/:id/full')
+   * async show(ctx: RequestContext) {
+   *   const row = await this.repo.findFullById(ctx.params.id, ctx.signal)
+   *   if (!row) return ctx.notFound()
+   *   ctx.json(row)
+   * }
+   * ```
+   *
+   * The repo passes `signal` to `db.query.<table>.findUnique({ signal })`;
+   * if the client disconnects mid-flight, the in-flight query rejects
+   * with `RelationalQueryCancelledError` instead of consuming the
+   * connection until completion.
+   *
+   * Implementation note — both `req.on('close')` and `res.on('close')`
+   * are wired so the signal aborts regardless of whether the close
+   * event lands on the request stream or the response stream first.
+   * Subsequent fires are no-ops (`AbortController.abort()` is
+   * idempotent).
+   */
+  get signal(): AbortSignal;
+  /** Session data (requires session middleware) */
+  get session(): any;
+  /**
+   * The authenticated user set by AuthAdapter.
+   * Reads from the per-request metadata store first (`ctx.set('user', ...)`),
+   * then falls back to `req.user` (set directly by AuthAdapter middleware).
+   *
+   * Extend the `AuthUser` interface via module augmentation in `@forinda/kickjs-auth`
+   * to get full typing.
+   *
+   * @example
+   * ```ts
+   * @Get('/me')
+   * @Authenticated()
+   * getProfile(ctx: RequestContext) {
+   *   const user = ctx.user
+   *   if (!user) return ctx.notFound()
+   *   return ctx.json({ user })
+   * }
+   * ```
+   */
+  get user(): MetaValue<'user', Record<string, any>> | undefined;
+  /**
+   * Tenant identifier for multi-tenant apps. Reads `user.tenantId` —
+   * populated either by `AuthAdapter.testMode({ tenantId })`, a tenant
+   * resolver middleware, or manually on the strategy's `mapPayload`.
+   *
+   * Augment `AuthUser` (or `ContextMeta['user']`) to widen the return
+   * type if your user shape guarantees a non-`string | undefined` id.
+   */
+  get tenantId(): string | undefined;
+  /**
+   * Effective role list for the current user. Prefers `user.tenantRoles`
+   * (populated by `AuthAdapterOptions.roleResolver` under a tenant) and
+   * falls back to `user.roles`. Returns an empty array when the user is
+   * absent or the shape has neither field.
+   */
+  get roles(): string[];
+  /**
+   * Parse the request query string into structured filters, sort, pagination, and search.
+   * Pass the result to an ORM query builder adapter (Drizzle, Prisma, Sequelize, etc.).
+   *
+   * Generic over the field config: when passed an inline literal (or
+   * `as const`), `filters[].field` and `sort[].field` are narrowed to
+   * the exact whitelisted field names. Pass nothing or a non-literal
+   * config and you get the loose `string` fallback.
+   *
+   * @param fieldConfig - Optional whitelist for filterable, sortable, and searchable fields
+   * @param options - Limits (`maxLimit`, `defaultLimit`, `maxSearchLength`) and an
+   *   `onReject` hook. By default a rejected/over-broad field is logged via
+   *   `console.warn` with the request id; pass an explicit `onReject` to override
+   *   (e.g. throw to return a 400), or `onReject: () => {}` to silence.
+   *
+   * @example
+   * ```ts
+   * @Get('/')
+   * async list(ctx: RequestContext) {
+   *   const parsed = ctx.qs({
+   *     filterable: ['status', 'priority'],
+   *     sortable: ['createdAt', 'title'],
+   *   } as const)
+   *   parsed.filters[0].field // typed as 'status' | 'priority'
+   *   parsed.sort[0].field    // typed as 'createdAt' | 'title'
+   * }
+   * ```
+   */
+  qs<TConfig extends QueryFieldConfig | undefined = undefined>(fieldConfig?: TConfig, options?: ParseQueryOptions): TypedParsedQuery<TConfig>;
+  /**
+   * Single uploaded file (requires `@FileUpload({ mode: 'single' })`).
+   * Wrapped in a dev-only Proxy that warns on mutation — see {@link body}.
+   * File metadata is set by the upload middleware and shouldn't be
+   * mutated downstream.
+   */
+  get file(): Express.Multer.File | undefined;
+  /**
+   * Array of uploaded files (requires `@FileUpload({ mode: 'array' })`).
+   * The array (and each entry in dev) is wrapped in a read-only Proxy
+   * that warns on `push`/`pop` and per-file mutation. Use
+   * `ctx.req.files` if you genuinely need the mutable Express handle.
+   */
+  get files(): Express.Multer.File[] | undefined;
+  /**
+   * Read a value from the per-request metadata store.
+   *
+   * When `ContextMeta` has been augmented with a matching key, the return
+   * type is inferred automatically. For ad-hoc keys, pass a generic:
+   * `ctx.get<MyType>('custom')`.
+   */
+  get<K extends string>(key: K): MetaValue<K> | undefined;
+  /**
+   * Write a value to the per-request metadata store. Throws when no
+   * AsyncLocalStorage frame is active — see {@link metadataForWrite}
+   * for why a silent fallback is the wrong default.
+   */
+  set<K extends string>(key: K, value: MetaValue<K>): void;
+  json(data: any, status?: number): RuntimeResponse;
+  created(data: any): RuntimeResponse;
+  noContent(): unknown;
+  /**
+   * @deprecated Prefer {@link ProblemSender.notFound | ctx.problem.notFound()},
+   * which emits an RFC 9457 — Problem Details response. This helper stays
+   * for backward compatibility and will not be removed.
+   */
+  notFound(message?: string): RuntimeResponse;
+  /**
+   * @deprecated Prefer {@link ProblemSender.badRequest | ctx.problem.badRequest()},
+   * which emits an RFC 9457 — Problem Details response. This helper stays
+   * for backward compatibility and will not be removed.
+   */
+  badRequest(message: string): RuntimeResponse;
+  /**
+   * RFC 9457 — Problem Details for HTTP APIs response helper.
+   * https://datatracker.ietf.org/doc/html/rfc9457
+   *
+   * `ctx.problem(...)` sends a canonical problem-detail response with
+   * `Content-Type: application/problem+json`. The convenience methods
+   * (`ctx.problem.notFound`, `.badRequest`, etc.) pre-fill `status` +
+   * `title` for the common codes.
+   *
+   * `type` defaults to `about:blank` (§3.1.1); `title` defaults to the
+   * IANA reason phrase for `status` (§3.1.4). Extension members per §3.2
+   * pass through unchanged.
+   *
+   * @example
+   * ```ts
+   * ctx.problem({
+   *   type: 'https://api.example.com/problems/out-of-credit',
+   *   status: 403,
+   *   detail: 'Your balance is 30, but that costs 50.',
+   *   instance: `/account/${ctx.user.id}/messages/${ctx.params.id}`,
+   *   balance: 30,
+   * })
+   *
+   * ctx.problem.notFound({ detail: 'User abc not found' })
+   * ctx.problem.validation(zodResult.error.issues)
+   * ```
+   *
+   * @see {@link ProblemException} for the exception-throwing equivalent
+   * (use it from services where `ctx` isn't in scope).
+   */
+  get problem(): ProblemSender;
+  private sendProblem;
+  html(content: string, status?: number): RuntimeResponse;
+  download(buffer: Buffer, filename: string, contentType?: string): RuntimeResponse;
+  /**
+   * Render a template using the registered view engine (EJS, Pug, Handlebars, etc.).
+   * Requires a ViewAdapter to be configured in bootstrap().
+   *
+   * @param template - Template name (without extension, relative to viewsDir)
+   * @param data - Data to pass to the template
+   *
+   * @example
+   * ```ts
+   * ctx.render('dashboard', { user, title: 'Dashboard' })
+   * ctx.render('emails/welcome', { name: 'Alice' })
+   * ```
+   */
+  render(template: string, data?: Record<string, any>): unknown;
+  /**
+   * Parse query params and return a standardized paginated response.
+   * Calls `ctx.qs()` internally, then wraps your data with pagination meta.
+   *
+   * @param fetcher - Async function that receives ParsedQuery and returns `{ data, total }`
+   * @param fieldConfig - Optional whitelist for filterable, sortable, searchable fields
+   *
+   * @example
+   * ```ts
+   * @Get('/')
+   * async list(ctx: RequestContext) {
+   *   return ctx.paginate(
+   *     async (parsed) => {
+   *       const data = await db.select().from(users)
+   *         .where(query.where).limit(parsed.pagination.limit)
+   *         .offset(parsed.pagination.offset).all()
+   *       const total = await db.select({ count: count() }).from(users).get()
+   *       return { data, total: total?.count ?? 0 }
+   *     },
+   *     { filterable: ['name', 'role'], sortable: ['createdAt'] },
+   *   )
+   * }
+   * ```
+   */
+  paginate<T, TConfig extends QueryFieldConfig | undefined = undefined>(fetcher: (parsed: TypedParsedQuery<TConfig>) => Promise<{
+    data: T[];
+    total: number;
+  }>, fieldConfig?: TConfig): Promise<RuntimeResponse>;
+  /**
+   * Start an SSE (Server-Sent Events) stream.
+   * Sets the correct headers and returns helpers to send events.
+   *
+   * @example
+   * ```ts
+   * @Get('/events')
+   * async stream(ctx: RequestContext) {
+   *   const sse = ctx.sse()
+   *
+   *   const interval = setInterval(() => {
+   *     sse.send({ time: new Date().toISOString() }, 'tick')
+   *   }, 1000)
+   *
+   *   sse.onClose(() => clearInterval(interval))
+   * }
+   * ```
+   */
+  sse(): {
+    /** Send an SSE event with optional event name and id */send: (data: any, event?: string, id?: string) => void; /** Send a comment (keeps connection alive) */
+    comment: (text: string) => void; /** Register a callback when the client disconnects */
+    onClose: (fn: () => void) => void; /** End the SSE stream */
+    close: () => void;
+  };
+}
+/**
+ * Short alias for `RequestContext` parameterised by a route shape.
+ *
+ * Use with `kick typegen`'s generated `KickRoutes` namespace for
+ * fully-typed `ctx.params`, `ctx.body`, and `ctx.query`. Metadata
+ * typing (`ctx.get()`, `ctx.set()`, `ctx.user`) comes from
+ * `ContextMeta` augmentation and works on all `RequestContext` instances.
+ *
+ * @example
+ * ```ts
+ * @Get('/:id')
+ * getUser(ctx: Ctx<KickRoutes.UserController['getUser']>) {
+ *   ctx.params.id      // typed from RouteShape
+ *   ctx.body           // typed from RouteShape
+ *   ctx.user           // typed from ContextMeta
+ *   ctx.get('tenant')  // typed from ContextMeta
+ * }
+ * ```
+ */
+type Ctx<TRoute extends RouteShape = RouteShape> = RequestContext<TRoute extends {
+  body: infer B;
+} ? B : any, TRoute extends {
+  params: infer P;
+} ? P : any, TRoute extends {
+  query: infer Q;
+} ? Q : any>;
+/**
+ * Global ambient registry of typed routes, populated by `kick typegen`.
+ *
+ * Each interface inside `KickRoutes` corresponds to a controller class;
+ * each property is one route method on that controller. The values
+ * conform to `RouteShape`.
+ *
+ * Empty by default — declarations come from `.kickjs/types/routes.d.ts`
+ * generated alongside the rest of the typegen output.
+ */
+declare global {
+  namespace KickRoutes {}
+} //# sourceMappingURL=context.d.ts.map
+//#endregion
+//#region src/http/runtime.d.ts
+/** HTTP verbs the router emits. Mirrors the decorator surface (@Get/@Post/...). */
+type RouteMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+/**
+ * A context-based handler: the runtime-neutral unit of the request pipeline.
+ * Contributors, route middleware (via {@link MiddlewareHandler}), and the
+ * terminal controller call all reduce to this shape. The runtime owns how a
+ * `CtxHandler` is wrapped onto its engine (Express wraps it in `(req, res,
+ * next)`; Fastify in its own handler).
+ */
+type CtxHandler = (ctx: RequestContext) => unknown | Promise<unknown>;
+/**
+ * Connect-style middleware — the portable middleware format. Built-in
+ * middleware and adopter-supplied Express middleware are this shape. The
+ * Express runtime hands them straight to `app.use`; later runtimes bridge
+ * them (Fastify via `@fastify/middie`, h3 via its node adapter).
+ *
+ * Typed as the Express handler union for M1 (Express is the only runtime);
+ * a future milestone narrows this to bare node `(req, res, next)` primitives
+ * once the driver layer lands.
+ */
+type ConnectMiddleware = RequestHandler | ErrorRequestHandler;
+/**
+ * One materialized route, as plain data. Produced by {@link buildRouteTable}
+ * from decorator metadata; consumed by {@link HttpRuntime.mountRoutes}.
+ *
+ * The shape is deliberately richer than a flat `CtxHandler[]`: `middlewares`
+ * keep the `(ctx, next)` signature (they may short-circuit or call `next(err)`),
+ * `contributorRunner` is a closure over the pre-built pipeline + container (the
+ * pipeline is built — and any cycle / missing-dep error thrown — at table-build
+ * time, i.e. boot), and `validation` / `upload` stay as metadata the runtime
+ * materializes its own way. Faithfully reproducing the legacy Express chain —
+ * not collapsing it — is what keeps M1 behavior-neutral.
+ */
+interface RouteEntry {
+  method: RouteMethod;
+  /** Path with `:param` segments — the portable subset all engines accept. */
+  path: string;
+  /** Class + method middleware, in execution order; each receives `(ctx, next)`. */
+  middlewares: MiddlewareHandler[];
+  /**
+   * Runs the contributor pipeline against `ctx` (populates `ctx.set(...)`),
+   * or `null` when no contributors apply. Closes over the built pipeline and
+   * the DI container so it stays engine-neutral; the runtime advances the
+   * chain (Express: call `next()`) once it resolves.
+   */
+  contributorRunner: CtxHandler | null;
+  /** Terminal handler: resolves the controller per-request and invokes it. */
+  handler: CtxHandler;
+  /** Introspection + runtime-materialized concerns (swagger/typegen read this). */
+  meta: RouteMeta;
+}
+/** Per-route metadata: introspection refs plus runtime-materialized concerns. */
+interface RouteMeta {
+  /**
+   * Owning controller class — for DI resolution and adapter introspection.
+   * Absent for ad-hoc routes registered through {@link AdapterHttp.route},
+   * which have no controller class behind them.
+   */
+  controller?: Constructor;
+  /** Handler method name on the controller, when there is one. */
+  handlerName?: string;
+  /** Zod/JSON-schema validation config from the route decorator, if any. */
+  validation?: RouteDefinition['validation'];
+  /** `@FileUpload` config, if present — the runtime supplies the backend. */
+  upload?: FileUploadConfig;
+}
+/** A controller's routes grouped under the module mount prefix. */
+type RouteTable = {
+  mountPath: string;
+  routes: RouteEntry[];
+}[];
+/**
+ * The response surface {@link RequestContext}'s helpers (`json` / `html` /
+ * `sse` / `download` / `render` / `problem`) drive, instead of calling Express
+ * `res` methods directly (spec §4.3). Sized so `express.Response` satisfies it
+ * structurally — under the Express runtime the driver IS the Express response,
+ * so there is no wrapping and no behavior change. Other runtimes (Fastify / h3)
+ * provide a thin object implementing this over their native reply.
+ *
+ * The terminal methods return `RuntimeResponse` for fluent chaining (Express's
+ * `Response` is assignable, since it is a superset).
+ */
+interface RuntimeResponse {
+  status(code: number): RuntimeResponse;
+  json(data: unknown): RuntimeResponse;
+  send(data: unknown): RuntimeResponse;
+  type(contentType: string): RuntimeResponse;
+  setHeader(name: string, value: string | number | readonly string[]): unknown;
+  render(view: string, data?: Record<string, unknown>): unknown;
+  writeHead(statusCode: number, headers?: Record<string, string>): unknown;
+  flushHeaders(): unknown;
+  write(chunk: string | Buffer): boolean;
+  end(data?: unknown): unknown;
+  once(event: 'close', listener: () => void): unknown;
+  readonly headersSent: boolean;
+}
+/**
+ * Per-runtime type map: the engine-native request / response / app types an
+ * `HttpRuntime` exposes through `ctx.req.raw` / `ctx.res.raw` / `AdapterContext.app`.
+ */
+interface RuntimeTypeMap {
+  request: unknown;
+  response: unknown;
+  app: unknown;
+}
+/** The Express runtime's native types — the default when nothing is augmented. */
+interface ExpressRuntimeTypes {
+  request: Request;
+  response: Response;
+  app: Express$1;
+}
+/**
+ * Augmentable runtime registry. Empty by default; the `kick/runtime` typegen
+ * plugin emits a `{ runtime: <RuntimeTypeMap> }` augmentation from the configured
+ * runtime, which flips the engine-native escape-hatch types — `AdapterContext.app`,
+ * `getRuntimeApp()`, and (once the driver layer lands) `ctx.req.raw` / `ctx.res.raw`
+ * — to that runtime. Mirrors `KickDbRegister` / `KickEnv`, so the type story is
+ * uniform with `kick/db` and env typing.
+ *
+ * @example
+ * ```ts
+ * // .kickjs/types/kick__runtime.d.ts — generated by typegen
+ * declare module '@forinda/kickjs' {
+ *   interface KickRuntimeRegister {
+ *     runtime: import('@forinda/kickjs/fastify').FastifyRuntimeTypes
+ *   }
+ * }
+ * ```
+ */
+interface KickRuntimeRegister {}
+/** The active runtime's type map — the augmented one, or Express by default. */
+type ActiveRuntime = KickRuntimeRegister extends {
+  runtime: infer R extends RuntimeTypeMap;
+} ? R : ExpressRuntimeTypes;
+/** Options passed to {@link HttpRuntime.createApp}. */
+interface RuntimeAppOptions {
+  /**
+   * Express `trust proxy` setting (and the equivalent on other engines). The
+   * function form is Express-specific; other runtimes interpret the simpler
+   * shapes (or normalize X-Forwarded-For themselves — see spec §10 Q1).
+   */
+  trustProxy?: boolean | string | number | string[] | ((ip: string, hopIndex: number) => boolean);
+}
+/** Where a connect middleware sits and what it scopes to. */
+interface UseConnectOptions {
+  path?: string | RegExp | ReadonlyArray<string | RegExp>;
+}
+/**
+ * Optional engine capabilities. Absence means the corresponding `ctx` feature
+ * raises a clear error on that runtime rather than failing obscurely.
+ */
+interface RuntimeCapabilities {
+  /** View-engine rendering (`ctx.render`). Express: true; Fastify/h3: false initially. */
+  render: boolean;
+  /** File uploads (`ctx.file` / `@FileUpload`). All engines, different backends. */
+  uploads: boolean;
+  /** Connect-style middleware. Express/Fastify(middie): true; h3: best-effort. */
+  connectMiddleware: boolean;
+  /**
+   * The engine parses request bodies itself (Fastify, h3). When true, the
+   * Application skips its default `express.json()` so the body stream isn't
+   * consumed twice (which would deadlock the engine's own parser). Express:
+   * false — it relies on the `express.json()` connect middleware.
+   */
+  nativeBodyParsing: boolean;
+}
+/**
+ * The engine driver. KickJS owns decorators → {@link RouteTable}, the
+ * contributor pipeline, the `RequestContext` surface, and error mapping. The
+ * runtime owns app/server creation, route materialization, connect-middleware
+ * registration, static serving, and the terminal not-found / error handlers.
+ *
+ * `expressRuntime()` is the default and the M1 reference implementation.
+ */
+interface HttpRuntime<TApp = unknown> {
+  readonly name: 'express' | 'fastify' | 'h3' | (string & {});
+  /** Create the engine app. Called once per Application (and per HMR rebuild). */
+  createApp(options?: RuntimeAppOptions): TApp;
+  /**
+   * Node-compatible request listener — the transport contract.
+   * `http.createServer(handler)` in prod, Vite post-middleware in dev. MUST
+   * invoke `next` (when given) instead of 404-ing if no route matched — the
+   * Vite dev chain depends on fall-through.
+   */
+  nodeHandler(app: TApp): (req: IncomingMessage, res: ServerResponse, next?: (err?: unknown) => void) => void;
+  /** Materialize the framework-built route table onto the engine. */
+  mountRoutes(app: TApp, table: RouteTable): void;
+  /** Register a connect-style middleware (built-ins + adopter middleware). */
+  useConnect(app: TApp, mw: ConnectMiddleware, opts?: UseConnectOptions): void;
+  /** Serve a static directory (swagger-ui assets, devtools SPA). */
+  serveStatic(app: TApp, prefix: string, dir: string): void;
+  /** Terminal not-found handler. */
+  setNotFound(app: TApp, mw: ConnectMiddleware): void;
+  /** Terminal error handler. */
+  setErrorHandler(app: TApp, mw: ConnectMiddleware): void;
+  readonly capabilities: RuntimeCapabilities;
+}
+/**
+ * The supported surface adapters use to add HTTP routes, mounts, static dirs,
+ * and middleware — engine-agnostic, in place of reaching for the raw Express
+ * `app` (spec §4.4). Exposed as {@link AdapterContext.http}. Built by the
+ * Application over the active {@link HttpRuntime}, so an adapter written against
+ * this works under any runtime; the raw `app` escape hatch stays available for
+ * the rare engine-specific need.
+ */
+interface AdapterHttp {
+  /** Register a single context-handler route (e.g. a docs or transport endpoint). */
+  route(method: RouteMethod, path: string, handler: CtxHandler): void;
+  /** Mount a pre-built route table under a path prefix. */
+  mount(prefix: string, routes: RouteEntry[]): void;
+  /** Serve a static directory under a path prefix. */
+  serveStatic(prefix: string, dir: string): void;
+  /** Register a connect-style middleware (optionally path-scoped). */
+  use(mw: ConnectMiddleware, opts?: UseConnectOptions): void;
+}
+//#endregion
+//#region src/core/adapter.d.ts
+/**
+ * Where in the middleware pipeline an adapter's middleware should be inserted.
+ *
+ * - `beforeGlobal` — runs **before** any user-defined global middleware.
+ *   Suitable for transport-level concerns (request tagging, low-level
+ *   request rewriting). Fires on every request.
+ * - `afterGlobal` — runs **after** global middleware, **before** module
+ *   routes are matched. Default for most adapter middleware (auth pre-checks,
+ *   tenant resolution, body shaping). Fires on every request.
+ * - `beforeRoutes` — runs just before module routes are mounted. Functionally
+ *   equivalent to `afterGlobal` for most cases; the explicit phase exists so
+ *   adapters that *must* sit at the very end of the pre-route stack can
+ *   declare intent. Fires on every request.
+ * - `afterRoutes` — sits **after** module routes but **before** error
+ *   handlers. **Fires only on fall-through** — when no route matched (404
+ *   path) or a route handler called `next()` without ending the response.
+ *   Controllers that respond with `ctx.json(...)` end the chain and skip
+ *   this phase, so it is *not* a "post-response" hook. For per-response
+ *   work (logging, metrics) use `res.on('finish', ...)` from inside an
+ *   earlier-phase middleware instead.
+ */
+type MiddlewarePhase = 'beforeGlobal' | 'afterGlobal' | 'beforeRoutes' | 'afterRoutes';
+/**
+ * Path scope for an {@link AdapterMiddleware} entry. Mirrors what
+ * Express's `app.use(path, handler)` accepts so adapters get the full
+ * range without learning a new mini-language:
+ *
+ * - A `string` prefix — `'/api'` matches `/api`, `/api/v1`, `/api/v1/x`.
+ * - A `RegExp` — `/^\/api\/v\d+/` matches `/api/v1`, `/api/v42`.
+ * - An array of either — `['/api', '/admin']` matches either prefix;
+ *   `['/api', /^\/internal\//]` mixes shapes.
+ *
+ * Omit to apply the middleware unconditionally (Express `app.use(handler)`).
+ */
+type MiddlewarePath = string | RegExp | ReadonlyArray<string | RegExp>;
+/** A middleware entry contributed by an adapter */
+interface AdapterMiddleware {
+  /**
+   * Express handler: either a `RequestHandler` (`(req, res, next) => …`)
+   * or an `ErrorRequestHandler` (`(err, req, res, next) => …`).
+   * Express dispatches based on arity, so the same field accepts both
+   * without a discriminant.
+   */
+  handler: RequestHandler | ErrorRequestHandler;
+  /** Which phase to insert into (default: 'afterGlobal') */
+  phase?: MiddlewarePhase;
+  /**
+   * Optional path scope. See {@link MiddlewarePath} for the accepted
+   * shapes (string prefix, RegExp, or an array mixing both). Omit to
+   * apply the middleware to every request that reaches this phase.
+   */
+  path?: MiddlewarePath;
+}
+/**
+ * Context passed to adapter lifecycle hooks.
+ * Populated by the Application — provides access to the Express app,
+ * DI container, http.Server, and environment info without requiring
+ * external type imports. Cast `app` or `server` if you need specific types.
+ *
+ * @example
+ * ```ts
+ * beforeMount({ app, container }: AdapterContext) {
+ *   app.use(myMiddleware())
+ * }
+ * ```
+ */
+interface AdapterContext {
+  /**
+   * Engine-agnostic HTTP surface — the supported way to add routes, mounts,
+   * static dirs, and middleware (spec §4.4). Prefer this over {@link app}:
+   * an adapter written against `http` works under any runtime.
+   */
+  http: AdapterHttp;
+  /**
+   * Engine-native application instance — Express under the default runtime,
+   * typed from the active runtime via {@link ActiveRuntime} (spec §4.3b).
+   * Escape hatch for genuinely engine-specific needs; for everything else use
+   * {@link http}.
+   */
+  app: ActiveRuntime['app'];
+  /** DI container */
+  container: Container;
+  /** Node.js http.Server — only available in afterStart */
+  server?: http.Server;
+  /** Current NODE_ENV value (default: 'development') */
+  env: string;
+  /** true when NODE_ENV === 'production' */
+  isProduction: boolean;
+}
+/**
+ * Adapters plug into the Application lifecycle.
+ * Implement this to add WebSocket, database, rate limiting, docs, etc.
+ *
+ * All hooks receive an `AdapterContext` populated by the framework.
+ * No external type imports needed — the context is fully typed from KickJS internals.
+ *
+ * @example
+ * ```ts
+ * import type { AppAdapter, AdapterContext } from '@forinda/kickjs/adapter'
+ *
+ * class SentryAdapter implements AppAdapter {
+ *   name = 'SentryAdapter'
+ *
+ *   beforeMount({ app, container }: AdapterContext) {
+ *     app.use(Sentry.expressRequestHandler())
+ *   }
+ *
+ *   afterStart({ server }: AdapterContext) {
+ *     // server is the http.Server — available after listen()
+ *   }
+ *
+ *   async shutdown() {
+ *     await Sentry.close(2000)
+ *   }
+ * }
+ * ```
+ */
+interface AppAdapter {
+  /**
+   * Human-readable name for logging and `dependsOn` resolution.
+   * Required when the adapter (or any other in the same set) declares
+   * `dependsOn` — sort errors will reference adapters by name.
+   */
+  name?: string;
+  /**
+   * Other adapter names that must mount before this one. The framework
+   * topologically sorts adapters at boot — cycles or unknown names throw
+   * via `MountCycleError` / `MissingMountDepError` so bad configurations
+   * fail boot rather than corrupt live traffic.
+   *
+   * Common pattern: `TenantAdapter` populates `req.tenant` and
+   * `AuthAdapter` reads it for tenant-scoped RBAC, so AuthAdapter
+   * declares `dependsOn = ['TenantAdapter']`. Adapters without
+   * `dependsOn` retain their declaration order.
+   *
+   * @example
+   * ```ts
+   * class AuthAdapter implements AppAdapter {
+   *   name = 'AuthAdapter'
+   *   dependsOn = ['TenantAdapter']
+   * }
+   * ```
+   */
+  dependsOn?: readonly KickJsPluginName[];
+  /**
+   * Return middleware entries to be inserted into the pipeline.
+   * The `phase` controls ordering relative to global middleware and routes.
+   */
+  middleware?(): AdapterMiddleware[];
+  /**
+   * Return Context Contributors (#107) that apply to every route in the
+   * application. Adapter-level contributors merge into the per-route
+   * pipeline at the `'adapter'` precedence level — they win over global
+   * contributors but lose to module, class, and method decorators.
+   *
+   * Useful for cross-cutting concerns: an auth adapter contributing
+   * `user`, a multi-tenant adapter contributing `tenant`, etc. Optional.
+   */
+  contributors?(): ContributorRegistrations;
+  /**
+   * Called before global middleware — register early routes (docs UI, health).
+   * May return a Promise — async rejections are caught and logged.
+   */
+  beforeMount?(ctx: AdapterContext): void | Promise<void>;
+  /**
+   * Called for each module route that gets mounted.
+   * Use this to collect route metadata (e.g. for OpenAPI spec generation).
+   */
+  onRouteMount?(controllerClass: Constructor, mountPath: string): void;
+  /**
+   * Called after modules are registered and the DI container is bootstrapped,
+   * before the HTTP server starts listening. **This is the correct hook for
+   * adapters that register DI bindings, resolve services, or otherwise prepare
+   * container-side state** (e.g. `container.registerInstance(MAILER, ...)`).
+   *
+   * `beforeStart` runs inside `app.setup()`, which means it also fires under
+   * `createTestApp` — adapters using this hook work in unit tests without
+   * needing a live HTTP server. See {@link afterStart} for the contrast.
+   *
+   * May return a Promise — async rejections are caught and logged.
+   */
+  beforeStart?(ctx: AdapterContext): void | Promise<void>;
+  /**
+   * Called after the HTTP server is listening — `ctx.server` is the live
+   * `http.Server`. **Use this hook only for work that genuinely needs a
+   * listening server**: attaching Socket.IO / WS upgrades, reading the bound
+   * port via `server.address()`, dispatching to the local server over HTTP,
+   * etc.
+   *
+   * `afterStart` does NOT fire under `createTestApp`, since tests call
+   * `app.setup()` and never `app.start()`. If your adapter only registers DI
+   * bindings or resolves services, use {@link beforeStart} — that hook runs
+   * in both production (`start()`) and tests (`setup()`).
+   *
+   * May return a Promise — async rejections are caught and logged.
+   */
+  afterStart?(ctx: AdapterContext): void | Promise<void>;
+  /**
+   * Called by the /health/ready endpoint. Return the health status of your adapter's
+   * backing service (database, Redis, queue, etc.).
+   */
+  onHealthCheck?(): Promise<{
+    name: string;
+    status: 'up' | 'down';
+  }>;
+  /** Called on shutdown — clean up connections */
+  shutdown?(): MaybePromise;
+  /**
+   * Optional DevTools introspection hook (architecture.md §23). Returns
+   * a snapshot describing this adapter's current state, metrics, and DI
+   * tokens. DevTools awaits the result, so async work is fine — but keep
+   * the implementation cheap (counters + flags, no DB round trips) since
+   * the topology endpoint polls on a short interval.
+   *
+   * The return type lives in `@forinda/kickjs` itself ({@link IntrospectionSnapshot})
+   * so adopters can author `introspect()` without importing the kit just
+   * to satisfy the contract. The kit's own `IntrospectionSnapshot` type
+   * stays structurally identical; either import works.
+   */
+  introspect?(): IntrospectionSnapshot | Promise<IntrospectionSnapshot>;
+  /**
+   * Optional DevTools tabs this adapter contributes (architecture.md §23).
+   * Returns an array of `DevtoolsTabDescriptor` shapes — typically one
+   * entry per adapter-owned panel (iframe / launch / html view).
+   *
+   * Same untyped-at-this-layer convention as {@link introspect}: adapter
+   * authors import `defineDevtoolsTab` (or the bare type) from
+   * `@forinda/kickjs-devtools-kit` so `@forinda/kickjs` doesn't take on
+   * a runtime dep on the kit.
+   */
+  devtoolsTabs?(): readonly unknown[];
+}
+/** Constructor type for AppAdapter classes */
+type AppAdapterClass = new () => AppAdapter;
+//#endregion
+export { CircuitBreaker as $, GroupAssetKeysResult as A, definePlugin as At, MountKind as B, IntrospectionSnapshot as Bt, Ctx as C, DefineModuleOptions as Ct, AssetKeyPair as D, DefinePluginOptions as Dt, RouteShape as E, BuildContext as Et, DefineAdapterOptions as F, KickJsPluginName as Ft, BuildPipelineOptions as G, mountSort as H, defineAdapter as I, KickJsPluginRegistry as It, SourcedRegistration as J, ContributorPipeline as K, DuplicateMountNameError as L, defineAugmentation as Lt, stripExt as M, ModuleRegistry as Mt, AdapterAsyncOptions as N, MutableModuleRegistry as Nt, AssetKeyStrategy as O, PluginAsyncOptions as Ot, AdapterFactory as P, AugmentationMeta as Pt, MissingContributorError as Q, MissingMountDepError as R, IntrospectFn as Rt, UseConnectOptions as S, defineModules as St, RequestContext as T, defineModule as Tt, RunContributorsOptions as U, MountSortItem as V, runContributors as W, ContributorCycleError as X, buildPipeline as Y, DuplicateContributorError as Z, RouteTable as _, FormatKickErrorOptions as _t, MiddlewarePath as a, getClassMetaOrUndefined as at, RuntimeResponse as b, formatKickError as bt, AdapterHttp as c, getMethodMeta as ct, ExpressRuntimeTypes as d, pushClassMeta as dt, CircuitBreakerOptions as et, HttpRuntime as f, pushMethodMeta as ft, RouteMethod as g, setMethodMeta as gt, RouteMeta as h, setInMetaRecord as ht, AppAdapterClass as i, getClassMeta as it, groupAssetKeys as j, KickPlugin as jt, GroupAssetKeysOptions as k, PluginFactory as kt, ConnectMiddleware as l, getMethodMetaOrUndefined as lt, RouteEntry as m, setInMetaMap as mt, AdapterMiddleware as n, CircuitBreakerStats as nt, MiddlewarePhase as o, getMetaMap as ot, KickRuntimeRegister as p, setClassMeta as pt, ContributorSource as q, AppAdapter as r, CircuitOpenError as rt, ActiveRuntime as s, getMetaRecord as st, AdapterContext as t, CircuitBreakerState as tt, CtxHandler as u, hasClassMeta as ut, RuntimeAppOptions as v, KickError as vt, DeepReadonly as w, ModuleFactory as wt, RuntimeTypeMap as x, ModuleList as xt, RuntimeCapabilities as y, KickErrorInit as yt, MountCycleError as z, IntrospectionKind as zt };
+//# sourceMappingURL=adapter-D_uzU-QA.d.mts.map